API reference

Brand terms

The workspace, members and invitations.

PUT/brand-terms

Set brand terms

Replaces the words the workspace's brand and its competitors' brands go by in search terms, used on every platform by GET /platforms/{platform}/search-term-brands: brand, competitors (term and competitor) and notBrand (a word Pluto found on its own that isn't a brand). Up to 200 words, each once; empty lists clear them. Answers what's set.

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

brandarray of strings
The workspace's own brand words.
competitorsarray of objects
Competitors' brand words.
notBrandarray of strings
Words that aren't brands.

Response200 OK

brand, competitors, notBrand.

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.
  • 422A word is empty, too long or named twice, on its field.
  • 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 PUT "$PLUTO_API/brand-terms" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 758daeb1-ffac-4710-8aeb-e726a31c87a1" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": [
      "Brevanne"
    ],
    "competitors": [
      {}
    ],
    "notBrand": [
      "Brevanne"
    ]
  }'