Agorapulse Drafts API
Create draft posts for review and approval.
OpenAPI Specification
openapi: 3.2.0
info:
title: Agorapulse Drafts API
description: "# Agorapulse API\n\nWelcome to the Agorapulse API. Use it to manage publishing, social inbox conversations, analytics and your content library programmatically.\n\nThe API is organized around REST, uses resource-oriented URLs, returns JSON, and relies on standard HTTP response codes and verbs.\n\n## Base URL\n\nAll requests go to the base URL shown in the **Server** selector, and every endpoint is versioned under a `/v1.0/` prefix.\n\n## Authentication\n\nThe API authenticates requests with an **API key** sent in the `X-API-KEY` HTTP header. Every request must include it:\n\n```http\nGET /v1.0/core/organizations HTTP/1.1\nHost: api.agorapulse.com\nX-API-KEY: your-api-key\n```\n\n```bash\ncurl https://api.agorapulse.com/v1.0/core/organizations \\\n -H \"X-API-KEY: your-api-key\"\n```\n\nKeep your API key secret: it grants access to your account's data. Requests without a valid key return `401 Unauthorized`.\n\n## Resource hierarchy\n\nMost resources are nested under an organization and a workspace:\n\n```\n/v1.0/<domain>/organizations/{organizationId}/workspaces/{workspaceId}/...\n```\n\nStart from `GET /v1.0/core/organizations` to discover your organizations, then list their workspaces and profiles.\n\n## Errors\n\nThe API uses conventional HTTP status codes: `2xx` for success, `4xx` for client errors (a missing or invalid parameter, an unknown resource, a missing API key), and `5xx` for server errors.\n\nError responses carry a JSON body describing the problem, except for `405`, `406` and `415`, which answer with a status only:\n\n```json\n{\n \"code\": 1005,\n \"subCode\": 1104,\n \"message\": \"Media not found: pubmedia_abc123\"\n}\n```\n\n`code` identifies the error family: either a global one (`1` internal, `2` unauthorized, `3` rate limit exceeded, `4` unprocessable input, `5` validation failed), or the component that produced the error. That component is usually the feature you addressed, but not always — a request whose path matches no endpoint is rejected by the API gateway itself and carries the gateway's own code, `1013`, whichever feature the path pointed at. `subCode` is optional and, when present, pinpoints the exact cause within that component; the endpoints that return one document its values. `message` is a human-readable explanation and is not meant to be parsed.\n\n## Webhooks\n\nAgorapulse can push events to your endpoints. See the **Webhooks** section for the available events (for example `PUBLISHING_POST` and `INBOX_ITEM`) and their payloads.\n"
version: '1.0'
contact:
name: Agorapulse API Support
url: https://www.agorapulse.com
email: support@agorapulse.com
x-logo:
url: docs/img/logo.svg
altText: Agorapulse
servers:
- url: https://api.agorapulse.com
description: Production
security:
- bearerAuth: []
tags:
- name: Drafts
description: Create draft posts for review and approval.
paths:
/v1.0/publishing/organizations/{organizationId}/workspaces/{workspaceId}/simple-drafts:
post:
tags:
- Drafts
summary: Create a simple draft (deprecated)
description: 'Deprecated: use POST /v1.0/publishing/organizations/{organizationId}/workspaces/{workspaceId}/drafts instead (one draft per profile; see the Drafts tag). This endpoint is frozen and will not receive new features such as per-network options.'
operationId: save_1
parameters:
- name: organizationId
in: path
description: Organization identifier
required: true
schema:
type: integer
- name: workspaceId
in: path
description: Workspace identifier
required: true
schema:
type: integer
requestBody:
description: Simple draft to create
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSimpleDraftOpenRequest'
required: true
responses:
'201':
description: Simple draft created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSimpleDraftOpenResponse'
'400':
description: Invalid request data
'404':
description: Organization or workspace not found
deprecated: true
components:
schemas:
CreateSimpleDraftOpenRequest:
required:
- type
type: object
properties:
text:
type: string
description: Text content of the draft
example: This is my social media post
type:
$ref: '#/components/schemas/PostType'
link:
type: string
description: Link URL to be included in the post
example: https://example.com
labels:
type: array
description: Set of labels/tags to categorize the draft
example:
- marketing
- promotion
items:
type: string
mediaUrls:
type: array
description: 'List of media URLs to be included. Deprecated: use ''media'' instead.'
example:
- https://example.com/image.jpg
deprecated: true
items:
type: string
media:
type: array
description: List of media items to be included. Takes precedence over 'mediaUrls' when both are provided.
items:
$ref: '#/components/schemas/PostMedia'
scheduling:
type: array
description: Scheduling configuration for different profiles
items:
$ref: '#/components/schemas/CreateSimpleDraftOpenRequest.ProfileScheduling'
networks:
type: object
description: Per-network publishing options, applied to every targeted profile of that network
allOf:
- $ref: '#/components/schemas/PostNetworks'
- type: object
description: Request to create a simple draft
InstagramPostOptions:
type: object
properties:
format:
type: object
description: 'Publishing surface: regular feed post (default), story, or reel. REEL also shares the reel on the feed.'
allOf:
- $ref: '#/components/schemas/InstagramPostFormat'
- type: object
firstComment:
type: object
description: First comment posted under the published post. Its 'media' is not supported on Instagram and is ignored.
allOf:
- $ref: '#/components/schemas/PostFirstComment'
- type: object
description: Instagram Business specific publishing options
PostStatus:
type: string
enum:
- DRAFT
- PUBLISHED
- FAILED
- SCHEDULED
CreateSimpleDraftOpenResponse:
required:
- groupOfPosts
type: object
properties:
groupOfPosts:
$ref: '#/components/schemas/GroupOfPostsSummary'
description: Response after creating a simple draft
LinkedinPostOptions:
type: object
properties:
firstComment:
type: object
description: First comment posted under the published post. Its 'media' is not supported on LinkedIn and is ignored.
allOf:
- $ref: '#/components/schemas/PostFirstComment'
- type: object
linkTitle:
type: string
description: Title of the link preview. Required on a LINK post.
example: How we ship our public API
linkDescription:
type: string
description: Description of the link preview, at most 4086 characters.
example: A short summary of the linked page.
poll:
type: object
description: Poll attached to the post. Supplying one replaces any poll already on the post.
allOf:
- $ref: '#/components/schemas/LinkedinPoll'
- type: object
description: LinkedIn specific publishing options, applied to company pages and personal accounts alike
Profile:
required:
- name
- network
- uid
type: object
properties:
uid:
minLength: 1
type: string
name:
type: string
network:
$ref: '#/components/schemas/Network'
PostType:
type: string
enum:
- TEXT
- PHOTO
- VIDEO
- PHOTO_AND_VIDEO
- LINK
- PDF
GroupOfPostsSummary:
required:
- agorapulseLink
- labels
- profileScheduling
- type
- uid
type: object
properties:
uid:
minLength: 1
type: string
agorapulseLink:
type: string
type:
$ref: '#/components/schemas/PostType'
labels:
type: array
items:
type: string
profileScheduling:
type: array
items:
$ref: '#/components/schemas/GroupOfPostsSummary.ProfileSchedulingSummary'
Network:
type: string
enum:
- BLUESKY
- FACEBOOK
- GOOGLE
- INSTAGRAM
- LINKEDIN
- PINTEREST
- THREADS
- TIKTOK
- TWITTER
- YOUTUBE
YoutubePostPrivacy:
type: string
description: Visibility of the published video on YouTube
enum:
- PUBLIC
- UNLISTED
- PRIVATE
YoutubePostOptions:
type: object
properties:
title:
type: string
description: Video title. Required by YouTube, at most 100 characters, and it cannot contain < or >.
example: How we ship our public API
privacy:
type: object
description: Visibility of the video. Defaults to PUBLIC when omitted, as the composer does.
allOf:
- $ref: '#/components/schemas/YoutubePostPrivacy'
- type: object
tags:
type: array
description: Video tags. They are comma-joined with every tag containing a space wrapped in quotes, and the result must stay under 500 characters.
example:
- public api
- openapi
items:
type: string
madeForKids:
type: boolean
description: Declare the video as made for kids.
notifySubscribers:
type: boolean
description: Notify the channel's subscribers of the upload.
embeddable:
type: boolean
description: Allow the video to be embedded on other sites.
license:
type: object
description: Licence the video is published under.
allOf:
- $ref: '#/components/schemas/YoutubePostLicense'
- type: object
description: YouTube channel specific publishing options
FacebookPostFormat:
type: string
description: Publishing surface of a Facebook Page post. REEL requires a video post.
enum:
- FEED
- STORY
- REEL
YoutubePostLicense:
type: string
description: Licence the video is published under
enum:
- STANDARD
- CREATIVE_COMMONS
InstagramPostFormat:
type: string
description: Publishing surface of an Instagram Business post. REEL requires a video post.
enum:
- FEED
- STORY
- REEL
GroupOfPostsSummary.SchedulingSummary:
required:
- publishingDate
- status
- uid
type: object
properties:
uid:
type: string
publishingDate:
type: string
format: date-time
status:
$ref: '#/components/schemas/PostStatus'
GroupOfPostsSummary.ProfileSchedulingSummary:
required:
- profile
- schedulingSummary
type: object
properties:
profile:
$ref: '#/components/schemas/Profile'
schedulingSummary:
type: array
items:
$ref: '#/components/schemas/GroupOfPostsSummary.SchedulingSummary'
PostNetworks:
type: object
properties:
facebook:
type: object
description: Options applied to every targeted Facebook Page profile
allOf:
- $ref: '#/components/schemas/FacebookPostOptions'
- type: object
youtube:
type: object
description: Options applied to every targeted YouTube channel profile
allOf:
- $ref: '#/components/schemas/YoutubePostOptions'
- type: object
instagram:
type: object
description: Options applied to every targeted Instagram Business profile
allOf:
- $ref: '#/components/schemas/InstagramPostOptions'
- type: object
linkedin:
type: object
description: Options applied to every targeted LinkedIn profile, company or personal
allOf:
- $ref: '#/components/schemas/LinkedinPostOptions'
- type: object
pinterest:
type: object
description: Options applied to every targeted Pinterest profile
allOf:
- $ref: '#/components/schemas/PinterestPostOptions'
- type: object
tiktok:
type: object
description: Options applied to every targeted TikTok profile
allOf:
- $ref: '#/components/schemas/TiktokPostOptions'
- type: object
description: Per-network publishing options, applied to every targeted profile of that network
LinkedinPollDuration:
type: string
description: How long the poll stays open for votes
enum:
- ONE_DAY
- THREE_DAYS
- SEVEN_DAYS
- FOURTEEN_DAYS
LinkedinPoll:
type: object
properties:
question:
type: string
description: Question asked, at most 140 characters.
example: Which topic should we cover next?
options:
type: array
description: Between 2 and 4 answers, each at most 30 characters, all distinct.
example:
- Public API
- Webhooks
items:
type: string
duration:
type: object
description: Defaults to THREE_DAYS, as the composer does.
allOf:
- $ref: '#/components/schemas/LinkedinPollDuration'
- type: object
description: Poll attached to the LinkedIn post. A poll and media are mutually exclusive.
PostFirstComment:
type: object
properties:
text:
type: string
description: Text of the comment
example: More details in the link below!
media:
type: object
description: Single media attached to the comment. 'altText' is ignored for comment media.
allOf:
- $ref: '#/components/schemas/PostMedia'
- type: object
description: Comment posted right after the post is published
CreateSimpleDraftOpenRequest.ProfileScheduling:
required:
- profileUid
type: object
properties:
profileUid:
minLength: 1
type: string
description: Unique identifier of the profile
example: profile_123
publishingDates:
type: array
description: List of publishing dates in ISO-8601 format
example:
- '2024-12-25T10:00:00.000Z'
- '2024-12-26T15:30:00.000Z'
items:
type: string
format: date-time
description: Scheduling configuration for a specific profile
PostMedia:
required:
- altText
- url
type: object
properties:
url:
type: string
altText:
type: string
FacebookPostOptions:
type: object
properties:
format:
type: object
description: 'Publishing surface: regular feed post (default), story, or reel. REEL requires a video post.'
allOf:
- $ref: '#/components/schemas/FacebookPostFormat'
- type: object
firstComment:
type: object
description: First comment posted under the published post
allOf:
- $ref: '#/components/schemas/PostFirstComment'
- type: object
linkTitle:
type: string
description: Title of the link preview. Only sent when the page owns the linked URL, which is re-checked at publish time.
example: How we ship our public API
linkDescription:
type: string
description: Description of the link preview. Only sent when the page owns the linked URL.
example: A short summary of the linked page.
videoTitle:
type: string
description: Title of the video, at most 200 characters. Ignored on a reel.
example: Behind the scenes
description: Facebook Page specific publishing options
PinterestPostOptions:
type: object
properties:
boardId:
type: string
description: 'Board the pin is published to. Required: Pinterest cannot publish a pin without one.'
example: '1234567890123456789'
title:
type: string
description: Title of the pin, at most 100 characters.
example: Our summer collection
link:
type: string
description: Destination the pin links to, a well-formed http(s) URL. Distinct from the post link.
example: https://example.com/collection
description: Pinterest specific publishing options
TiktokPostOptions:
type: object
properties:
privacy:
type: object
description: Who can see the post. Defaults to PUBLIC_TO_EVERYONE when omitted.
allOf:
- $ref: '#/components/schemas/TiktokPostPrivacy'
- type: object
commentEnabled:
type: boolean
description: Allow comments on the post. Omitting this disables them.
duetEnabled:
type: boolean
description: Allow other creators to duet the video. Omitting this disables duets.
stitchEnabled:
type: boolean
description: Allow other creators to stitch the video. Omitting this disables stitches.
autoAddMusicEnabled:
type: boolean
description: Let TikTok add a soundtrack to a photo post. Omitting this leaves it off.
description: TikTok specific publishing options
TiktokPostPrivacy:
type: string
description: Audience of a TikTok post. The account's own settings may narrow what TikTok accepts.
enum:
- PUBLIC_TO_EVERYONE
- MUTUAL_FOLLOW_FRIENDS
- FOLLOWER_OF_CREATOR
- SELF_ONLY
securitySchemes:
bearerAuth:
type: apiKey
name: X-API-KEY
in: header
HookSignature:
description: 'The signature of the webhook request, used to verify the authenticity of the request.
The signature is a SHA256 HMAC signature computed on the request body using the shared secret from your webhook subscription.
'
type: apiKey
name: X-Hook-Signature
in: header
x-tagGroups:
- name: Account & Workspaces
tags:
- Organizations
- Workspaces
- Profiles
- Groups
- name: Publishing
tags:
- Drafts
- Calendar notes
- Pinterest boards
- name: Content Library
tags:
- Media
- name: Inbox & Engagement
tags:
- Conversations
- Items
- Replies
- name: Analytics & Reporting
tags:
- Reports
- name: System
tags:
- Health