API reference

Country groups

Named groups of countries for targeting.

GET/country-groups

List country groups

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

countryGroupsarray of objectsRequired
Groups.
countryGroups[].countryCodesarray of strings
Countries.
countryGroups[].idstring (uuid)Required
ID.
countryGroups[].namestring
Name.
countryGroups[].versioninteger
Increments on every change; send as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/country-groups" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/country-groups

Create a country group

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

countryCodesarray of stringsRequired
Countries.
idstring (uuid)
Optional ID.
namestringRequired
Name.

Response201 Created

countryCodesarray of strings
Countries.
idstring (uuid)Required
ID.
namestring
Name.
versioninteger
Increments on every change; send as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/country-groups" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 500e6621-c93a-4d6e-a631-6feb99fa4500" \
  -H "Content-Type: application/json" \
  -d '{
    "countryCodes": [
      "US"
    ],
    "id": "d2162b73-4128-4e69-82db-418ad890557f",
    "name": "North America"
  }'
PATCH/country-groups/{id}

Update a country group

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe country group's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

countryCodesarray of strings
Countries.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
namestring
Name.

Response200 OK

countryCodesarray of strings
Countries.
idstring (uuid)Required
ID.
namestring
Name.
versioninteger
Increments on every change; send as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/country-groups/d2162b73-4128-4e69-82db-418ad890557f" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: d3d81e95-b5f3-47d9-bb30-14963944159e" \
  -H "Content-Type: application/json" \
  -d '{
    "countryCodes": [
      "US"
    ],
    "expectedVersion": 3,
    "name": "North America"
  }'
DELETE/country-groups/{id}

Delete a country group

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe country group's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

Done; no content.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/country-groups/d2162b73-4128-4e69-82db-418ad890557f" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: b0cebd89-b21e-405b-ae12-e5b4f789fd5d"