Campaigns

get/v1/campaignsList campaigns
post/v1/campaignsCreate campaign
get/v1/campaigns/{id}Get campaign
patch/v1/campaigns/{id}Update campaign
put/v1/campaigns/{id}/statusSet campaign status
put/v1/campaigns/{id}/personasSet campaign personas
get/v1/campaigns/{id}/resultsGet campaign results
get/v1/campaigns/{id}/deliverablesList campaign deliverables
put/v1/campaigns/{id}/posts/{postId}Add post to campaign
del/v1/campaigns/{id}/posts/{postId}Remove post from campaign
get/v1/personasSearch personas
post/v1/personasGet or create persona
patch/v1/personas/{id}Update persona
post/v1/personas/{id}/archiveArchive persona
get/v1/objectivesSearch objectives
post/v1/objectivesGet or create objective
patch/v1/objectives/{id}Update objective
post/v1/objectives/{id}/archiveArchive objective

List campaigns

get/v1/campaigns

List the workspace's campaigns with post counts per status and this month's cadence progress. Filter with a comma-separated `status`. Needs campaigns:view; client-visibility members receive the client view without internal notes.

Query parameters

statusstring

Response 200

Campaigns

dataarray of objectrequired
Child attributes
- idstringrequired
- workspaceIdstringrequired
- audiencestringrequired
  One ofteamclient
- namestringrequired
- objectiveIdstringrequirednullable
- creativeDirectionstringrequirednullable
- statusstringrequired
  One ofdraftactivecompletedarchived
- startAtstring (date-time)requirednullable
- endAtstring (date-time)requirednullable
- colorstringrequirednullable
- ongoingbooleanrequired
- personaIdsarray of stringrequired
- postCountsmap of numberrequired
- coverImageUrlstringrequirednullable
- internalNotesstringnullable
- monthlyPostTargetintegernullable
- progressCountintegernullable
- createdBystringnullable
- createdAtstring (date-time)
- updatedAtstring (date-time)

Errors

400: Invalid status filter
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found

Request

curl "https://api.posty.social/v1/campaigns" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "id": "string",
      "workspaceId": "string",
      "audience": "team",
      "name": "string",
      "objectiveId": "string",
      "creativeDirection": "string",
      "status": "draft",
      "startAt": "2026-01-15T09:30:00.000Z",
      "endAt": "2026-01-15T09:30:00.000Z",
      "color": "string",
      "ongoing": true,
      "personaIds": [
        "string"
      ],
      "postCounts": {
        "key": 1
      },
      "coverImageUrl": "string",
      "internalNotes": "string",
      "monthlyPostTarget": 1,
      "progressCount": 1,
      "createdBy": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}

Create campaign

post/v1/campaigns

Create a campaign: a bounded launch (startAt and endAt) or an ongoing theme (no dates plus monthlyPostTarget). Needs campaigns:create and counts against the plan's campaign limit (402 when reached).

Request body

namestringrequired
Min length 1 · Max length 200
objectiveIdstringnullable
Min length 1
personaIdsarray of string
Default [] · Max items 50
creativeDirectionstringnullable
Max length 5000
internalNotesstringnullable
Max length 5000
statusstring
One ofdraftactivecompletedarchived
Default "draft"
startAtstring (date-time)nullable
endAtstring (date-time)nullable
monthlyPostTargetintegernullable
Min 1 · Max 1000
colorstringnullable
Max length 32

Response 201

Campaign created

idstringrequired
workspaceIdstringrequired
audiencestringrequired
One ofteamclient
namestringrequired
objectiveIdstringrequirednullable
creativeDirectionstringrequirednullable
statusstringrequired
One ofdraftactivecompletedarchived
startAtstring (date-time)requirednullable
endAtstring (date-time)requirednullable
colorstringrequirednullable
ongoingbooleanrequired
personaIdsarray of stringrequired
postCountsmap of numberrequired
coverImageUrlstringrequirednullable
internalNotesstringnullable
monthlyPostTargetintegernullable
progressCountintegernullable
createdBystringnullable
createdAtstring (date-time)
updatedAtstring (date-time)

Errors

400: Invalid request
401: Unauthenticated
402: Campaign limit reached
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X POST "https://api.posty.social/v1/campaigns" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "objectiveId": "string",
  "personaIds": [],
  "creativeDirection": "string",
  "internalNotes": "string",
  "status": "draft",
  "startAt": "2026-01-15T09:30:00.000Z",
  "endAt": "2026-01-15T09:30:00.000Z",
  "monthlyPostTarget": 1,
  "color": "string"
}'

Response 201

{
  "id": "string",
  "workspaceId": "string",
  "audience": "team",
  "name": "string",
  "objectiveId": "string",
  "creativeDirection": "string",
  "status": "draft",
  "startAt": "2026-01-15T09:30:00.000Z",
  "endAt": "2026-01-15T09:30:00.000Z",
  "color": "string",
  "ongoing": true,
  "personaIds": [
    "string"
  ],
  "postCounts": {
    "key": 1
  },
  "coverImageUrl": "string",
  "internalNotes": "string",
  "monthlyPostTarget": 1,
  "progressCount": 1,
  "createdBy": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Get campaign

get/v1/campaigns/{id}

Get one campaign's brief: objective, personas, creative direction, dates or monthly target, and post counts. Needs campaigns:view; client-visibility members receive the client view without internal notes.

Path parameters

idstringrequired

Response 200

Campaign

idstringrequired
workspaceIdstringrequired
audiencestringrequired
One ofteamclient
namestringrequired
objectiveIdstringrequirednullable
creativeDirectionstringrequirednullable
statusstringrequired
One ofdraftactivecompletedarchived
startAtstring (date-time)requirednullable
endAtstring (date-time)requirednullable
colorstringrequirednullable
ongoingbooleanrequired
personaIdsarray of stringrequired
postCountsmap of numberrequired
coverImageUrlstringrequirednullable
internalNotesstringnullable
monthlyPostTargetintegernullable
progressCountintegernullable
createdBystringnullable
createdAtstring (date-time)
updatedAtstring (date-time)

Errors

401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found

Request

curl "https://api.posty.social/v1/campaigns/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "audience": "team",
  "name": "string",
  "objectiveId": "string",
  "creativeDirection": "string",
  "status": "draft",
  "startAt": "2026-01-15T09:30:00.000Z",
  "endAt": "2026-01-15T09:30:00.000Z",
  "color": "string",
  "ongoing": true,
  "personaIds": [
    "string"
  ],
  "postCounts": {
    "key": 1
  },
  "coverImageUrl": "string",
  "internalNotes": "string",
  "monthlyPostTarget": 1,
  "progressCount": 1,
  "createdBy": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Update campaign

patch/v1/campaigns/{id}

Edit a campaign's brief. Omitted fields are left alone and null clears a field. Needs campaigns:update. Use set_campaign_status for status and set_campaign_personas for target personas.

Path parameters

idstringrequired

Request body

namestring
Min length 1 · Max length 200
objectiveIdstringnullable
Min length 1
creativeDirectionstringnullable
Max length 5000
internalNotesstringnullable
Max length 5000
startAtstring (date-time)nullable
endAtstring (date-time)nullable
monthlyPostTargetintegernullable
Min 1 · Max 1000
colorstringnullable
Max length 32

Response 200

Campaign updated

idstringrequired
workspaceIdstringrequired
audiencestringrequired
One ofteamclient
namestringrequired
objectiveIdstringrequirednullable
creativeDirectionstringrequirednullable
statusstringrequired
One ofdraftactivecompletedarchived
startAtstring (date-time)requirednullable
endAtstring (date-time)requirednullable
colorstringrequirednullable
ongoingbooleanrequired
personaIdsarray of stringrequired
postCountsmap of numberrequired
coverImageUrlstringrequirednullable
internalNotesstringnullable
monthlyPostTargetintegernullable
progressCountintegernullable
createdBystringnullable
createdAtstring (date-time)
updatedAtstring (date-time)

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X PATCH "https://api.posty.social/v1/campaigns/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "objectiveId": "string",
  "creativeDirection": "string",
  "internalNotes": "string",
  "startAt": "2026-01-15T09:30:00.000Z",
  "endAt": "2026-01-15T09:30:00.000Z",
  "monthlyPostTarget": 1,
  "color": "string"
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "audience": "team",
  "name": "string",
  "objectiveId": "string",
  "creativeDirection": "string",
  "status": "draft",
  "startAt": "2026-01-15T09:30:00.000Z",
  "endAt": "2026-01-15T09:30:00.000Z",
  "color": "string",
  "ongoing": true,
  "personaIds": [
    "string"
  ],
  "postCounts": {
    "key": 1
  },
  "coverImageUrl": "string",
  "internalNotes": "string",
  "monthlyPostTarget": 1,
  "progressCount": 1,
  "createdBy": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Set campaign status

put/v1/campaigns/{id}/status

Move a campaign between draft, active, completed and archived. Needs campaigns:update, and campaigns:archive to archive. An archived campaign accepts no new deliverables.

Path parameters

idstringrequired

Request body

statusstringrequired
One ofdraftactivecompletedarchived

Response 200

Campaign status set

idstringrequired
workspaceIdstringrequired
audiencestringrequired
One ofteamclient
namestringrequired
objectiveIdstringrequirednullable
creativeDirectionstringrequirednullable
statusstringrequired
One ofdraftactivecompletedarchived
startAtstring (date-time)requirednullable
endAtstring (date-time)requirednullable
colorstringrequirednullable
ongoingbooleanrequired
personaIdsarray of stringrequired
postCountsmap of numberrequired
coverImageUrlstringrequirednullable
internalNotesstringnullable
monthlyPostTargetintegernullable
progressCountintegernullable
createdBystringnullable
createdAtstring (date-time)
updatedAtstring (date-time)

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X PUT "https://api.posty.social/v1/campaigns/$ID/status" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "draft"
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "audience": "team",
  "name": "string",
  "objectiveId": "string",
  "creativeDirection": "string",
  "status": "draft",
  "startAt": "2026-01-15T09:30:00.000Z",
  "endAt": "2026-01-15T09:30:00.000Z",
  "color": "string",
  "ongoing": true,
  "personaIds": [
    "string"
  ],
  "postCounts": {
    "key": 1
  },
  "coverImageUrl": "string",
  "internalNotes": "string",
  "monthlyPostTarget": 1,
  "progressCount": 1,
  "createdBy": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Set campaign personas

put/v1/campaigns/{id}/personas

Replace the set of personas a campaign targets with personaIds (find or create them with get_or_create_persona). Needs campaigns:update.

Path parameters

idstringrequired

Request body

personaIdsarray of stringrequired
Max items 50

Response 200

Campaign personas set

campaignIdstringrequired
personaIdsarray of stringrequired

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X PUT "https://api.posty.social/v1/campaigns/$ID/personas" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "personaIds": [
    "string"
  ]
}'

Response 200

{
  "campaignId": "string",
  "personaIds": [
    "string"
  ]
}

Get campaign results

get/v1/campaigns/{id}/results

Campaign performance over the last `days` (default 30, clamped to the plan's analytics retention): comparative findings plus totals, per-post and per-persona reach. available is false when the plan keeps no analytics. Needs campaigns:view; client-visibility members get headline numbers and findings only.

Path parameters

idstringrequired

Query parameters

daysinteger
Default 30 · Min 1 · Max 365

Response 200

Campaign results

campaignIdstringrequired
audiencestringrequired
One ofteamclient
availablebooleanrequired
findingsarray of stringrequired
windowDaysinteger
totalsobjectnullable
Child attributes
- reachnumberrequired
- impressionsnumberrequired
- likesnumberrequired
- commentsnumberrequired
- sharesnumberrequired
- savesnumberrequired
- clicksnumberrequired
- postCountnumberrequired
postsarray of object
Child attributes
- postIdstringrequired
- bodystringrequired
- personaIdstringrequirednullable
- reachnumberrequired
- engagementsnumberrequired
personasarray of object
Child attributes
- personaIdstringrequired
- namestringrequired
- reachnumberrequired
- engagementsnumberrequired
- postCountnumberrequired
reachnumber
impressionsnumber
engagementsnumber
postCountnumber

Errors

401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found

Request

curl "https://api.posty.social/v1/campaigns/$ID/results" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "campaignId": "string",
  "audience": "team",
  "available": true,
  "findings": [
    "string"
  ],
  "windowDays": 1,
  "totals": {
    "reach": 1,
    "impressions": 1,
    "likes": 1,
    "comments": 1,
    "shares": 1,
    "saves": 1,
    "clicks": 1,
    "postCount": 1
  },
  "posts": [
    {
      "postId": "string",
      "body": "string",
      "personaId": "string",
      "reach": 1,
      "engagements": 1
    }
  ],
  "personas": [
    {
      "personaId": "string",
      "name": "string",
      "reach": 1,
      "engagements": 1,
      "postCount": 1
    }
  ],
  "reach": 1,
  "impressions": 1,
  "engagements": 1,
  "postCount": 1
}

List campaign deliverables

get/v1/campaigns/{id}/deliverables

List the posts filed under a campaign with their summary text, status, schedule, persona, platforms and a signed thumbnail URL. Needs posts:view; post statuses the caller may not see are left out.

Path parameters

idstringrequired

Query parameters

limitinteger
Default 200 · Min 1 · Max 500

Response 200

Campaign deliverables

dataarray of objectrequired
Child attributes
- idstringrequired
- bodystringrequired
- statusstringrequired
  One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
- scheduledAtstring (date-time)requirednullable
- updatedAtstring (date-time)required
- personaIdstringrequirednullable
- channelIdsarray of stringrequired
- platformsarray of stringrequired
  One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
- thumbnailstringrequirednullable

Errors

401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found

Request

curl "https://api.posty.social/v1/campaigns/$ID/deliverables" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "id": "string",
      "body": "string",
      "status": "draft",
      "scheduledAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "personaId": "string",
      "channelIds": [
        "string"
      ],
      "platforms": [
        "bluesky"
      ],
      "thumbnail": "string"
    }
  ]
}

Add post to campaign

put/v1/campaigns/{id}/posts/{postId}

File an existing post under this campaign as a deliverable, moving it out of any other campaign, and optionally set the persona it speaks to. Needs posts:update; the post must still be editable and the campaign not archived.

Path parameters

idstringrequired
postIdstringrequired

Request body

personaIdstringnullable
Min length 1

Response 200

Post filed

postIdstringrequired
campaignIdstringrequirednullable
personaIdstringrequirednullable
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X PUT "https://api.posty.social/v1/campaigns/$ID/posts/$POST_ID" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "personaId": "string"
}'

Response 200

{
  "postId": "string",
  "campaignId": "string",
  "personaId": "string",
  "status": "draft"
}

Remove post from campaign

del/v1/campaigns/{id}/posts/{postId}

Detach a post from this campaign and clear its persona. The post itself is kept. Needs posts:update; answers 404 when the post is not in this campaign.

Path parameters

idstringrequired
postIdstringrequired

Response 204

Post detached

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X DELETE "https://api.posty.social/v1/campaigns/$ID/posts/$POST_ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 204

No content

Search personas

get/v1/personas

Search the workspace's personas (target audiences) by name, case-insensitively. Archived personas are excluded unless includeArchived is true. Needs campaigns:view.

Query parameters

querystring
Max length 200
includeArchivedstring
One oftruefalse
limitinteger
Default 20 · Min 1 · Max 50

Response 200

Personas

dataarray of objectrequired
Child attributes
- idstringrequired
- workspaceIdstringrequired
- namestringrequired
- descriptionstringrequirednullable
- colorstringrequirednullable
- templateKeystringrequirednullable
- archivedAtstring (date-time)requirednullable
- createdAtstring (date-time)required
- updatedAtstring (date-time)required

Errors

401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found

Request

curl "https://api.posty.social/v1/personas" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "id": "string",
      "workspaceId": "string",
      "name": "string",
      "description": "string",
      "color": "string",
      "templateKey": "string",
      "archivedAt": "2026-01-15T09:30:00.000Z",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}

Get or create persona

post/v1/personas

Return the workspace persona with this name (matched case-insensitively), creating it when none exists. created tells which happened; an existing persona's fields are not changed. Needs campaigns:create.

Request body

namestringrequired
Min length 1 · Max length 200
descriptionstringnullable
Max length 5000
colorstringnullable
Max length 32
templateKeystringnullable
Max length 100

Response 200

Existing persona

personaobjectrequired
Child attributes
- idstringrequired
- workspaceIdstringrequired
- namestringrequired
- descriptionstringrequirednullable
- colorstringrequirednullable
- templateKeystringrequirednullable
- archivedAtstring (date-time)requirednullable
- createdAtstring (date-time)required
- updatedAtstring (date-time)required
createdbooleanrequired

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X POST "https://api.posty.social/v1/personas" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "string",
  "color": "string",
  "templateKey": "string"
}'

Response 200

{
  "persona": {
    "id": "string",
    "workspaceId": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "templateKey": "string",
    "archivedAt": "2026-01-15T09:30:00.000Z",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  },
  "created": true
}

Update persona

patch/v1/personas/{id}

Rename a persona or change its description or color. Needs campaigns:update.

Path parameters

idstringrequired

Request body

namestring
Min length 1 · Max length 200
descriptionstringnullable
Max length 5000
colorstringnullable
Max length 32

Response 200

Persona updated

idstringrequired
workspaceIdstringrequired
namestringrequired
descriptionstringrequirednullable
colorstringrequirednullable
templateKeystringrequirednullable
archivedAtstring (date-time)requirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X PATCH "https://api.posty.social/v1/personas/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "string",
  "color": "string"
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "name": "string",
  "description": "string",
  "color": "string",
  "templateKey": "string",
  "archivedAt": "2026-01-15T09:30:00.000Z",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Archive persona

post/v1/personas/{id}/archive

Archive a persona so pickers stop offering it (archived: false restores it). Existing campaign and post links are kept. Needs campaigns:archive.

Path parameters

idstringrequired

Request body

archivedboolean
Default true

Response 200

Persona archived or restored

idstringrequired
workspaceIdstringrequired
namestringrequired
descriptionstringrequirednullable
colorstringrequirednullable
templateKeystringrequirednullable
archivedAtstring (date-time)requirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X POST "https://api.posty.social/v1/personas/$ID/archive" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "archived": true
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "name": "string",
  "description": "string",
  "color": "string",
  "templateKey": "string",
  "archivedAt": "2026-01-15T09:30:00.000Z",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Search objectives

get/v1/objectives

Search the workspace's campaign objectives by name, case-insensitively. Archived objectives are excluded unless includeArchived is true. Needs campaigns:view.

Query parameters

querystring
Max length 200
includeArchivedstring
One oftruefalse
limitinteger
Default 20 · Min 1 · Max 50

Response 200

Objectives

dataarray of objectrequired
Child attributes
- idstringrequired
- workspaceIdstringrequired
- namestringrequired
- descriptionstringrequirednullable
- targetMetricKeystringrequirednullable
- targetValueintegerrequirednullable
- templateKeystringrequirednullable
- archivedAtstring (date-time)requirednullable
- createdAtstring (date-time)required
- updatedAtstring (date-time)required

Errors

401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found

Request

curl "https://api.posty.social/v1/objectives" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "id": "string",
      "workspaceId": "string",
      "name": "string",
      "description": "string",
      "targetMetricKey": "string",
      "targetValue": 1,
      "templateKey": "string",
      "archivedAt": "2026-01-15T09:30:00.000Z",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}

Get or create objective

post/v1/objectives

Return the workspace objective with this name (matched case-insensitively), creating it when none exists. created tells which happened; an existing objective's fields are not changed. Needs campaigns:create.

Request body

namestringrequired
Min length 1 · Max length 200
descriptionstringnullable
Max length 5000
targetMetricKeystringnullable
Max length 100
targetValueintegernullable
Min 0
templateKeystringnullable
Max length 100

Response 200

Existing objective

objectiveobjectrequired
Child attributes
- idstringrequired
- workspaceIdstringrequired
- namestringrequired
- descriptionstringrequirednullable
- targetMetricKeystringrequirednullable
- targetValueintegerrequirednullable
- templateKeystringrequirednullable
- archivedAtstring (date-time)requirednullable
- createdAtstring (date-time)required
- updatedAtstring (date-time)required
createdbooleanrequired

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X POST "https://api.posty.social/v1/objectives" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "string",
  "targetMetricKey": "string",
  "targetValue": 1,
  "templateKey": "string"
}'

Response 200

{
  "objective": {
    "id": "string",
    "workspaceId": "string",
    "name": "string",
    "description": "string",
    "targetMetricKey": "string",
    "targetValue": 1,
    "templateKey": "string",
    "archivedAt": "2026-01-15T09:30:00.000Z",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  },
  "created": true
}

Update objective

patch/v1/objectives/{id}

Rename an objective or change its description, target metric or target value. Needs campaigns:update.

Path parameters

idstringrequired

Request body

namestring
Min length 1 · Max length 200
descriptionstringnullable
Max length 5000
targetMetricKeystringnullable
Max length 100
targetValueintegernullable
Min 0

Response 200

Objective updated

idstringrequired
workspaceIdstringrequired
namestringrequired
descriptionstringrequirednullable
targetMetricKeystringrequirednullable
targetValueintegerrequirednullable
templateKeystringrequirednullable
archivedAtstring (date-time)requirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X PATCH "https://api.posty.social/v1/objectives/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "string",
  "targetMetricKey": "string",
  "targetValue": 1
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "name": "string",
  "description": "string",
  "targetMetricKey": "string",
  "targetValue": 1,
  "templateKey": "string",
  "archivedAt": "2026-01-15T09:30:00.000Z",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Archive objective

post/v1/objectives/{id}/archive

Archive an objective so pickers stop offering it (archived: false restores it). Campaigns pointing at it are kept. Needs campaigns:archive.

Path parameters

idstringrequired

Request body

archivedboolean
Default true

Response 200

Objective archived or restored

idstringrequired
workspaceIdstringrequired
namestringrequired
descriptionstringrequirednullable
targetMetricKeystringrequirednullable
targetValueintegerrequirednullable
templateKeystringrequirednullable
archivedAtstring (date-time)requirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required

Errors

400: Invalid request
401: Unauthenticated
403: Missing scope, or campaigns are disabled
404: Not found
409: Conflicting change

Request

curl -X POST "https://api.posty.social/v1/objectives/$ID/archive" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "archived": true
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "name": "string",
  "description": "string",
  "targetMetricKey": "string",
  "targetValue": 1,
  "templateKey": "string",
  "archivedAt": "2026-01-15T09:30:00.000Z",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}