Content

Creating, scheduling, publishing, and managing social content

Content is the core resource in the Maeve Social API. A content item represents a draft, scheduled post, published post, or failed post for a connected social account.

Content lifecycle

draft -> scheduled -> sent
                 -> failed

Immediate publishing is explicit. Use intent: "publish_now" when creating content, or call the publish endpoint for an existing draft or scheduled item.

Creating content

curl -X POST https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/content \
  -H "Authorization: Bearer $MAEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "integration-uuid",
    "intent": "schedule",
    "scheduledAt": "2027-01-01T12:00:00Z",
    "captions": {
      "canonical": "Hello world!",
      "overrides": {}
    }
  }'

Field	Required	Description
`integrationId`	Yes	Connected account to publish to
`intent`	No	`draft`, `schedule`, or `publish_now`. Defaults to `draft`
`captions`	No	Canonical caption and optional per-platform overrides
`contentMedia`	No	Array of media relationships to attach, max 10
`scheduledAt`	Required for `schedule`	ISO 8601 timestamp with timezone
`internalTitle`	No	Internal planning title, not sent to providers
`publishTitle`	No	Provider-facing title for platforms that support or require one
`notes`	No	Internal rich-text notes
`settings`	No	Strict platform-specific publishing settings
`threadMessages`	No	Array of thread/reply messages, max 20

Response:

{
  "data": {
    "id": "content-uuid",
    "status": "scheduled"
  },
  "meta": null
}

Draft, scheduled, and publish now

Omit intent or set draft: Create a draft.
Set intent: "schedule" with scheduledAt: Schedule for the specified time.
Set intent: "publish_now": Queue the content for immediate publish.

Caption overrides

Use captions.canonical for the default caption. Add overrides when a platform needs different copy:

{
  "captions": {
    "canonical": "Default copy",
    "overrides": {
      "instagram": "Instagram-specific copy",
      "linkedin": "LinkedIn-specific copy"
    }
  }
}

Supported override keys are x, linkedin, youtube, instagram, facebook, threads, tiktok, and pinterest.

Media attachments

Attach media with contentMedia, not mediaIds:

{
  "contentMedia": [
    {
      "mediaId": "media-uuid",
      "order": 0
    }
  ]
}

Each attachment can also include optional crop, cover, user tag, and product tag metadata where supported by the platform.

Thread content

Thread messages use the same canonical caption and media relationship shape:

{
  "integrationId": "integration-uuid",
  "intent": "schedule",
  "scheduledAt": "2027-01-01T12:00:00Z",
  "captions": {
    "canonical": "Thread opener",
    "overrides": {}
  },
  "threadMessages": [
    {
      "captions": {
        "canonical": "Second post",
        "overrides": {}
      }
    },
    {
      "captions": {
        "canonical": "Third post",
        "overrides": {}
      },
      "contentMedia": [
        {
          "mediaId": "media-uuid"
        }
      ]
    }
  ]
}

Listing content

curl "https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/content?status=scheduled&limit=10" \
  -H "Authorization: Bearer $MAEVE_API_KEY"

Query parameters

Parameter	Default	Description
`status`	public statuses	Filter by `draft`, `scheduled`, `sent`, or `failed`
`integrationId`	none	Filter by connected account
`workflowStatus`	none	Filter by internal workflow status
`sortBy`	service default	`createdAt`, `updatedAt`, `scheduledAt`, or `priority`
`sortDirection`	service default	`asc` or `desc`
`limit`	20	Results per page, 1-100
`offset`	0	Pagination offset

When no status filter is set, the default list is limited to public statuses. Review-held content can be included with explicit review lifecycle filters shown in the OpenAPI reference.

Response:

{
  "data": [
    {
      "id": "content-uuid",
      "internalTitle": null,
      "publishTitle": null,
      "captions": {
        "canonical": "Hello world!",
        "overrides": {}
      },
      "resolvedCaption": "Hello world!",
      "status": "scheduled",
      "scheduledAt": "2027-01-01T12:00:00.000Z",
      "error": null,
      "integrationId": "integration-uuid",
      "platform": "instagram",
      "platformUsername": "your_handle",
      "contentMedia": [
        {
          "mediaId": "media-uuid",
          "order": 0
        }
      ],
      "media": [
        {
          "id": "media-uuid",
          "url": "https://media.maevesocial.com/...",
          "type": "image/png"
        }
      ],
      "threadSize": 1
    }
  ],
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 42,
    "hasMore": true
  }
}

Getting one content item

curl https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/content/CONTENT_ID \
  -H "Authorization: Bearer $MAEVE_API_KEY"

The detail response includes integration info, attached media, thread messages, metadata, and sanitized platform settings.

Updating content

Only draft and scheduled content can be updated with the general update route. All fields are optional; provided fields replace the existing values.

curl -X PATCH https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/content/CONTENT_ID \
  -H "Authorization: Bearer $MAEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "captions": {
      "canonical": "Updated copy",
      "overrides": {}
    },
    "scheduledAt": "2027-06-01T12:00:00Z"
  }'

Response:

{
  "data": {
    "id": "content-uuid",
    "status": "scheduled"
  },
  "meta": null
}

Publishing now

Force-publish a draft or scheduled item immediately:

curl -X POST https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/content/CONTENT_ID/publish \
  -H "Authorization: Bearer $MAEVE_API_KEY"

The post is queued for immediate publish. The response returns status: "scheduled" until the publish job completes.

Deleting content

curl -X DELETE https://api.maevesocial.com/v1/workspaces/WORKSPACE_ID/content/CONTENT_ID \
  -H "Authorization: Bearer $MAEVE_API_KEY"

Returns 204 No Content on success.

PreviousWorkspaces NextMedia