> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nushir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List posts

> Posts in a date window. Both bounds are required — there is no
unbounded listing.




## OpenAPI

````yaml public-api/openapi.yaml GET /posts
openapi: 3.1.0
info:
  title: Nushir Public API
  version: 1.0.0
  description: >
    Schedule, publish and measure social posts on Nushir from your own code.


    Every route below is derived from the running application

    (`public.integrations.controller.ts`), so this document describes what the

    API actually does rather than what it is intended to do.


    ## Base URL


    ```

    https://platform.nushir.com/api/public/v1

    ```


    ## Authentication


    Send your key in the `Authorization` header. There is no `Bearer` prefix.


    ```

    Authorization: your-api-key

    ```


    Two kinds of credential are accepted on the same header:


    - **An API key**, created in *Settings → Developers*. It is scoped to the
      organisation that created it.
    - **An OAuth token**, issued to an approved app. These are recognised by
      their `pos_` prefix and resolve to the organisation that granted access.

    A missing or unrecognised credential returns `401`.


    ## Rate limits


    **90 requests per hour** per organisation, counted across every endpoint.

    Crossing the limit returns `429`; the window is one hour from each request.


    ## Try it from these pages


    Every endpoint page has a runnable panel. Paste your API key into the

    `Authorization` field, fill the parameters, and send - the request runs

    against your real organisation, so anything you create or delete is real.


    ## Channel or integration?


    The interface says **channel**. The API says **integration**. They are the

    same object; the name simply never got reconciled. Anywhere this document

    says *integration*, the calendar calls it a channel.


    ## Dates


    All dates are ISO-8601 in **UTC**. A post scheduled for
    `2026-09-01T09:00:00Z`

    publishes at 09:00 UTC regardless of the timezone on the account.


    ## Errors


    | Status | Meaning |

    |---|---|

    | `400` | The body failed validation. The response names the offending
    fields. |

    | `401` | Missing or invalid `Authorization` header. |

    | `403` | Authenticated, but the plan does not permit the action. |

    | `404` | No such object **in your organisation**. |


    A `404` is returned rather than `403` when an object exists but belongs to

    someone else, so the API never confirms that another organisation's id is

    real.
servers:
  - url: https://platform.nushir.com/api/public/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Integrations
    description: The connected social channels.
  - name: Posts
    description: Create, schedule, inspect and delete posts.
  - name: Uploads
    description: Get media into the library so a post can reference it.
  - name: Analytics
    description: Performance figures, where the platform reports them.
  - name: Notifications
    description: Account-level messages.
  - name: Video
    description: Generated video, where enabled.
paths:
  /posts:
    get:
      tags:
        - Posts
      summary: List posts
      description: |
        Posts in a date window. Both bounds are required — there is no
        unbounded listing.
      operationId: listPosts
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: customer
          in: query
          required: false
          schema:
            type: string
          description: Restrict to one client group.
      responses:
        '200':
          description: Posts in the window.
          content:
            application/json:
              schema:
                type: object
                properties:
                  posts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Post'
        '400':
          description: A date was missing or not a valid ISO-8601 string.
components:
  schemas:
    Post:
      type: object
      properties:
        id:
          type: string
        content:
          type: string
        publishDate:
          type: string
          format: date-time
        releaseURL:
          type: string
          nullable: true
          description: The live URL, once the platform has returned one.
        state:
          type: string
          enum:
            - QUEUE
            - PUBLISHED
            - ERROR
            - DRAFT
        integration:
          $ref: '#/components/schemas/Integration'
    Integration:
      type: object
      properties:
        id:
          type: string
          description: Use this wherever a route takes an integration id.
        name:
          type: string
          description: The channel's display name, as shown on the calendar.
        identifier:
          type: string
          description: >-
            The platform this channel posts to — `x`, `linkedin`, `tiktok`,
            `instagram`, and so on. This value decides which `settings` object a
            post must carry.
          example: tiktok
        picture:
          type: string
          description: Avatar URL, as reported by the platform.
        disabled:
          type: boolean
          description: >-
            A disabled channel stays on the account and keeps its history, but
            is skipped when a post is published.
        profile:
          type: string
          description: The handle or profile id on the platform.
        customer:
          type: object
          nullable: true
          description: The client group this channel belongs to, if any.
          properties:
            id:
              type: string
            name:
              type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Your API key from *Settings → Developers*, or an OAuth token beginning
        `pos_`. Sent raw — do **not** prefix it with `Bearer`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.