Skip to content

Get Post API — GET {{API_BASE_URL}}/v1/posts/{postId}

The Get Post API retrieves a single post by its postId so a client can inspect the complete stored record before deciding what to display, edit, or act on next. Use it when you already have an identifier and need the authoritative title, content, status, scheduling fields, mediaItems, per-platform results, and timestamps in one response. The request is a GET to {{API_BASE_URL}}/v1/posts/{postId}, where postId is the only path parameter and the access key is supplied in the x-access-key header.

Get Post API — GET {{API_BASE_URL}}/v1/posts/{postId}

The Get Post API uses a single operation: GET {{API_BASE_URL}}/v1/posts/{postId}. Replace postId in the path with the identifier of the post you want to retrieve, and send the request with the x-access-key header set to your access key. No query parameters or request-body fields are documented in the captured contract for this operation, so a client should not add undocumented parameters when checking a post. If the identifier is missing or malformed in your own code, fix the path construction before sending the request, because the server contract expects postId to be present as a required string path parameter.

Authorization

Authorization is supplied through the accessKey credential in the x-access-key header. Send the header on every request to this endpoint. The captured contract does not document a specific status code for authentication failures, so treat a missing or invalid key as a client configuration issue to resolve rather than retrying the same request unchanged. Do not place the key in the path, query string, or response handling code. Keep the token out of logs and error messages, and verify that your HTTP client is actually sending the header name exactly as x-access-key, since a differently named header will not satisfy the documented contract.

Path Parameters

The path contains one required parameter: postId, a string described as the post identifier. In the 200 response, post.postId is also a required string and is described as the MongoDB ObjectId of the Post document, so the value you request and the value returned should be compared directly when validating a response. URL-encode the identifier if your client library requires it, and avoid appending extra path segments. A practical failure check is to confirm that the request URL contains exactly one postId segment after /v1/posts/ before you debug response parsing.

Response Body

A successful lookup returns 200 with application/json and a body containing success as a required boolean and post as a required object. The post object carries the core record: postId, origin, isExternal, title, content, status, scheduledFor, timezone, mediaItems, platforms, crosspostingEnabled, rawRequestBody, createdAt, and updatedAt, plus an optional externalSource object. Treat the field map in the table titled 200 response field map as the parsing contract, including which fields are required, which may be null, and which use date-time strings. In particular, scheduledFor is a required string-or-null date-time field, so a null value is a valid state to handle rather than a parsing error, and timezone is a required string that should be read alongside scheduledFor when presenting a scheduled time.

200 application/json

The 200 response example in the code example titled 200 application/json response example shows the full nested shape, including mediaItems and platforms arrays. Read mediaItems as an array of media objects, each with a required type, url, filename, size, and mimeType, and an optional altText accessibility description. Read platforms as an array of per-platform objects, each with a required platform, status, content, platformPostId, platformPostUrl, publishedAt, errorMessage, and warningMessage, where several of those fields are string-or-null. The top-level status and each platform status use the same enum set: draft, pending, scheduled, publishing, published, failed, or partial. Use platformPostUrl only when it is a non-null string, because the contract allows null for a platform that has not produced a published URL.

404 application/json

When the post cannot be found, the documented failure response is 404 with application/json and a body containing success as a required boolean and message as a required string. Handle this branch separately from a 200 response: check the HTTP status first, then read message for the failure detail, and do not attempt to read a post object that the 404 contract does not provide. A useful client check is to branch on status code before parsing, log the postId you requested and the returned message without logging the x-access-key value, and surface a not-found state in the interface instead of treating the response as an empty post. The code example titled 404 application/json response example reproduces the captured source placeholder exactly for contract parity; it is an unexecuted placeholder sample, not observed runtime behavior, and its success value should not be read as expected error semantics.

Reading the response and origin-modular request example

To interpret a returned post, start with status to understand the overall state, then inspect each entry in platforms for its own status, errorMessage, and warningMessage. A platform entry can carry an errorMessage or warningMessage as a non-null string even when the overall post looks usable, so per-platform checks are necessary before presenting a platform result as successful. If a platform content field is null, the documented meaning is that the top-level content was used for that platform; if it is a string, it is the per-platform text override that was used. Similarly, publishedAt and platformPostId may be null, and crosspostingEnabled tells you whether crossposting was enabled for the post as a boolean. For external records, externalSource is optional and, when present, contains accountId, platformPostId, mediaType, thumbnailUrl, and lastSyncedAt, with mediaType limited to image, video, reel, or carousel or null and thumbnailUrl allowed to be null. The request example in the code example titled Get Post API request example shows the origin-modular form to use with a placeholder postId and token, without claiming that the example has been executed.

Path parameters
FieldRequiredTypeNotes
postIdRequiredstringPost identifier; sole path parameter.

Exact captured contract; origin modularized only.

Authorization header
FieldRequiredTypeNotes
x-access-keyRequiredstringAuthorization header carrying the accessKey credential; shown as <token> in the source.

Exact captured contract; no token value supplied.

200 response field map
FieldRequiredTypeNotes
successRequiredbooleanTop-level success flag.
postRequiredobjectThe retrieved post record.
post.postIdRequiredstringMongoDB ObjectId of the Post document.
post.originRequiredstringEnum: "postpeer" | "external".
post.isExternalRequiredbooleanWhether the post is external.
post.externalSourceOptionalobjectExternal origin details; see externalSource rows below.
post.externalSource.accountIdRequired when externalSource is presentstringAccount identifier for the external source.
post.externalSource.platformPostIdRequired when externalSource is presentstringPlatform-side post identifier.
post.externalSource.mediaTypeRequired when externalSource is presentstring | nullEnum: "image" | "video" | "reel" | "carousel", or null.
post.externalSource.thumbnailUrlRequired when externalSource is presentstring | nullThumbnail URL or null.
post.externalSource.lastSyncedAtRequired when externalSource is presentstringDate-time.
post.titleRequiredstringPost title; for external YouTube posts, the video title.
post.contentRequiredstringPost content.
post.statusRequiredstringEnum: "draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial".
post.scheduledForRequiredstring | nullISO 8601 scheduled datetime, or null.
post.timezoneRequiredstringTimezone string.
post.mediaItemsRequiredarray<object>Attached media; see mediaItems rows below.
post.mediaItems[].typeRequiredstringEnum: "image" | "video" | "gif".
post.mediaItems[].urlRequiredstringMedia URL.
post.mediaItems[].altTextOptionalstringAccessibility description supplied for this image.
post.mediaItems[].filenameRequiredstringMedia filename.
post.mediaItems[].sizeRequirednumberMedia size.
post.mediaItems[].mimeTypeRequiredstringMedia MIME type.
post.platformsRequiredarray<object>Per-platform results; see platforms rows below.
post.platforms[].platformRequiredstringEnum: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness".
post.platforms[].statusRequiredstringEnum: "draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial".
post.platforms[].contentRequiredstring | nullPer-platform text override; null when top-level content was used.
post.platforms[].platformPostIdRequiredstring | nullPlatform post identifier or null.
post.platforms[].platformPostUrlRequiredstring | nullDirect URL to the published post, or null.
post.platforms[].publishedAtRequiredstring | nullDate-time or null.
post.platforms[].errorMessageRequiredstring | nullPer-platform failure detail or null.
post.platforms[].warningMessageRequiredstring | nullPer-platform warning detail or null.
post.crosspostingEnabledRequiredbooleanWhether crossposting was enabled.
post.rawRequestBodyRequiredobjectRaw request body object with string keys.
post.createdAtRequiredstringDate-time.
post.updatedAtRequiredstringDate-time.

Exact captured contract; enums, nullability, and date-time formats preserved.

404 response field map
FieldRequiredTypeNotes
successRequiredbooleanTop-level success flag.
messageRequiredstringFailure message.

Exact captured contract; sample is unexecuted source placeholder.

Get Post API request example
curl -X GET "{{API_BASE_URL}}/v1/posts/{postId}" \
  -H "x-access-key: <token>"
200 application/json response example
{
  "success": true,
  "post": {
    "postId": "string",
    "origin": "postpeer",
    "isExternal": true,
    "externalSource": {
      "accountId": "string",
      "platformPostId": "string",
      "mediaType": "image",
      "thumbnailUrl": "string",
      "lastSyncedAt": "2019-08-24T14:15:22Z"
    },
    "title": "string",
    "content": "string",
    "status": "draft",
    "scheduledFor": "2019-08-24T14:15:22Z",
    "timezone": "string",
    "mediaItems": [
      {
        "type": "image",
        "url": "string",
        "altText": "string",
        "filename": "string",
        "size": 0,
        "mimeType": "string"
      }
    ],
    "platforms": [
      {
        "platform": "twitter",
        "status": "draft",
        "content": "string",
        "platformPostId": "string",
        "platformPostUrl": "string",
        "publishedAt": "2019-08-24T14:15:22Z",
        "errorMessage": "string",
        "warningMessage": "string"
      }
    ],
    "crosspostingEnabled": true,
    "rawRequestBody": {},
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
404 application/json response example
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.postobject__2Yes
response#1response.post.postIdstring__3YesMongoDB ObjectId of the Post document
response#1response.post.originstring__4Yes
response#1response.post.origin[variant1]string__4_extends:__5kind: schemaValueIn; value: "postpeer"
response#1response.post.origin[variant2]string__4_extends:__6kind: schemaValueIn; value: "external"
response#1response.post.isExternalboolean__7Yes
response#1response.post.externalSourceobject__8No
response#1response.post.externalSource.accountIdstring__9Yes
response#1response.post.externalSource.platformPostIdstring__10Yes
response#1response.post.externalSource.mediaTypestring | null__11Yeskind: schemaValueIn; value: "image" | "video" | "reel" | "carousel"
response#1response.post.externalSource.mediaType[variant1]string__11_type:stringkind: schemaValueIn; value: "image" | "video" | "reel" | "carousel"
response#1response.post.externalSource.mediaType[variant2]null__11_type:nullkind: schemaValueIn; value: "image" | "video" | "reel" | "carousel"
response#1response.post.externalSource.thumbnailUrlstring | null__12Yes
response#1response.post.externalSource.thumbnailUrl[variant1]string__12_type:string
response#1response.post.externalSource.thumbnailUrl[variant2]null__12_type:null
response#1response.post.externalSource.lastSyncedAtstring__13Yeskind: schemaFormat; value: date-time
response#1response.post.titlestring__14YesPost title. For external YouTube posts, this is the video title.
response#1response.post.contentstring__15Yes
response#1response.post.statusstring__16Yeskind: schemaValueIn; value: "draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial"
response#1response.post.scheduledForstring | null__17YesISO 8601 scheduled datetimekind: schemaFormat; value: date-time
response#1response.post.scheduledFor[variant1]string__17_type:stringISO 8601 scheduled datetimekind: ; value: date-time
response#1response.post.scheduledFor[variant2]null__17_type:nullISO 8601 scheduled datetimekind: ; value: date-time
response#1response.post.timezonestring__18Yes
response#1response.post.mediaItemsarray<object>__19Yes
response#1response.post.mediaItems[]object__20
response#1response.post.mediaItems[].typestring__21Yeskind: ; value: "image" | "video" | "gif"
response#1response.post.mediaItems[].urlstring__22Yes
response#1response.post.mediaItems[].altTextstring__23NoAccessibility description supplied for this image.
response#1response.post.mediaItems[].filenamestring__24Yes
response#1response.post.mediaItems[].sizenumber__25Yes
response#1response.post.mediaItems[].mimeTypestring__26Yes
response#1response.post.platformsarray<object>__27Yes
response#1response.post.platforms[]object__28
response#1response.post.platforms[].platformstring__29Yeskind: ; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#1response.post.platforms[].statusstring__30Yeskind: ; value: "draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial"
response#1response.post.platforms[].contentstring | null__31YesPer-platform text override that was used for this platform. Null when the top-level content was used.
response#1response.post.platforms[].content[variant1]string__31_type:stringPer-platform text override that was used for this platform. Null when the top-level content was used.
response#1response.post.platforms[].content[variant2]null__31_type:nullPer-platform text override that was used for this platform. Null when the top-level content was used.
response#1response.post.platforms[].platformPostIdstring | null__32Yes
response#1response.post.platforms[].platformPostId[variant1]string__32_type:string
response#1response.post.platforms[].platformPostId[variant2]null__32_type:null
response#1response.post.platforms[].platformPostUrlstring | null__33YesDirect URL to the published post
response#1response.post.platforms[].platformPostUrl[variant1]string__33_type:stringDirect URL to the published post
response#1response.post.platforms[].platformPostUrl[variant2]null__33_type:nullDirect URL to the published post
response#1response.post.platforms[].publishedAtstring | null__34Yeskind: ; value: date-time
response#1response.post.platforms[].publishedAt[variant1]string__34_type:stringkind: ; value: date-time
response#1response.post.platforms[].publishedAt[variant2]null__34_type:nullkind: ; value: date-time
response#1response.post.platforms[].errorMessagestring | null__35Yes
response#1response.post.platforms[].errorMessage[variant1]string__35_type:string
response#1response.post.platforms[].errorMessage[variant2]null__35_type:null
response#1response.post.platforms[].warningMessagestring | null__36Yes
response#1response.post.platforms[].warningMessage[variant1]string__36_type:string
response#1response.post.platforms[].warningMessage[variant2]null__36_type:null
response#1response.post.crosspostingEnabledboolean__37Yes
response#1response.post.rawRequestBodyobject__38Yes
response#1response.post.rawRequestBody.[key: string]anytrueNo
response#1response.post.createdAtstring__39Yeskind: ; value: date-time
response#1response.post.updatedAtstring__40Yeskind: ; value: date-time
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.messagestring__2Yes