Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

List Posts

On this page
GET/api/posts

Availability: pending. This endpoint is specified ahead of implementation and is not yet live on the hosted API; it ships through recoupable/app#2241. Do not rely on it until this notice is removed.

The account's posts, newest first, with each one's status and live URL.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/posts' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request GET \
  --url 'https://recoup-api.vercel.app/api/posts'

Parameters

Query parameters

account_idstring

Optional. Act on behalf of another account you can access. Defaults to the calling account.

statusstring · enum

Optional. Return only posts in this state.

Values: "scheduled", "publishing", "posted", "failed", "cancelled"

platformPostPlatform

Optional. Return only posts to this platform.

limitinteger

Optional. Maximum posts to return, newest first.

Default: 20

offsetinteger

Optional. Number of posts to skip, for paging.

Default: 0

Responses

200Posts in the requested account, newest first.

application/json

statusstring · enum

Status of the request

Values: "success"

postsarray<Post>

Posts, newest first. Empty when the account has none.

Item properties for posts
idstring

The post's id.

format: uuid

account_idstring

The account whose connection posts.

format: uuid

platformstring · enum

Target platform. The account must have this platform connected.

Values: "instagram", "x", "linkedin", "youtube"

sub_account_idstring | null

LinkedIn organization URN when posting as a Page, else null.

statusstring · enum

Lifecycle phase. scheduled until publish_at, publishing while the platform upload runs, then posted or failed. cancelled only from scheduled.

Values: "scheduled", "publishing", "posted", "failed", "cancelled"

video_urlstring

The video that is or was published.

cover_urlstring | null

The cover or thumbnail image, if any.

titlestring | null

Submitted title.

descriptionstring | null

Submitted body text.

privacystring | null

Submitted YouTube visibility.

tagsarray | null

Submitted YouTube tags.

Properties for tags

string

publish_atstring | null

Requested publish time. Null when published on creation.

format: date-time

post_urlstring | null

Live URL on the platform. Null until posted.

error_messagestring | null

Why publishing failed, as returned by the platform (e.g. a daily upload quota). Null unless status is failed.

text_verifiedboolean | null

Whether the live text, re-read from the platform after posting, equals the submitted title/description. Null until checked.

created_atstring

When the post was created.

format: date-time

updated_atstring

When the post last changed.

format: date-time

400Invalid query parameter.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["description"]

Item properties for missing_fields
oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

401Unauthorized.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["description"]

Item properties for missing_fields
oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

403Access denied to the specified account_id.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["description"]

Item properties for missing_fields
oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

500Internal server error.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["description"]

Item properties for missing_fields
oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download social.json
View operation source
json
{
  "summary": "List posts",
  "description": "**Availability: pending.** This endpoint is specified ahead of implementation and is not yet live on the hosted API; it ships through recoupable/app#2241. Do not rely on it until this notice is removed.\n\nThe account's posts, newest first, with each one's status and live URL.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "account_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Optional. Act on behalf of another account you can access. Defaults to the calling account."
    },
    {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "scheduled",
          "publishing",
          "posted",
          "failed",
          "cancelled"
        ]
      },
      "description": "Optional. Return only posts in this state."
    },
    {
      "name": "platform",
      "in": "query",
      "required": false,
      "schema": {
        "$ref": "#/components/schemas/PostPlatform"
      },
      "description": "Optional. Return only posts to this platform."
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 50,
        "default": 20
      },
      "description": "Optional. Maximum posts to return, newest first."
    },
    {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 0,
        "default": 0
      },
      "description": "Optional. Number of posts to skip, for paging."
    }
  ],
  "responses": {
    "200": {
      "description": "Posts in the requested account, newest first.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PostListResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid query parameter.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PostErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PostErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Access denied to the specified `account_id`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PostErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PostErrorResponse"
          }
        }
      }
    }
  },
  "x-recoup-availability": "pending"
}