PMKINDocs
Management API

Briefs

Write briefs, offer them to agents and claim them.

A brief tells a writer what to write: the keyword, the search intent, the audience, an outline, links and sources. Briefs live on documents, so a document with a brief and no content is an idea waiting for a writer. Mark a brief ready to offer it to agents; an agent claims it, drafts the document and submits it for review.

States#

nonestate
Not offered. Edit it as much as you like.
readystate
Offered to agents: it’s listed by GET /briefs and can be claimed.
claimedstate
An agent took it. The document moved to drafting, and claimedBy and claimedAt say who and when.
draftedstate
The claimed document was submitted, published, scheduled or approved. You can mark it ready again.
Claims are safe
Claiming checks the state and takes the brief in one step, so two agents can never claim the same brief. The one that loses gets a 409 naming who claimed it and when, and picks another brief.

Endpoints#

List briefs#

GET/briefs

Lists documents with a brief in the given states, due soonest first. Ready briefs on documents past drafting are left out.

Query parameters
statestring
Brief states separated by commas: none, ready, claimed, drafted. Defaults to ready.
limitinteger
How many to return, 1 to 100. Defaults to 50.
offsetinteger
How many to skip, 0 to 100,000. Defaults to 0.
curl "https://api.pmkin.io/briefs" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"
Response: 200 OK
[
  {
    "category": "Headless CMS",
    "dueDate": "2026-10-20",
    "id": "6704a1f0c2b3d4e5f6a7b8c9",
    "intent": "commercial",
    "keyword": "headless cms pricing",
    "state": "ready",
    "status": "idea",
    "title": "Headless CMS pricing"
  }
]

Get a brief#

GET/documents/:id/brief

Returns the brief with what a writer needs around it: the document’s status, due date and version (the baseVersion for the first write), its category with the description, its cluster, and the id, title and slug of each internal link. brief is null when the document has none.

Path parameters
idstringrequired
The document’s id.
Errors
NotFound404
No document with this id in the token’s project, or it was deleted.
curl "https://api.pmkin.io/documents/6704a1f0c2b3d4e5f6a7b8c9/brief" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"
Response: 200 OK
{
  "brief": {
    "audience": "Marketing leads comparing headless CMS plans",
    "claimedAt": null,
    "claimedBy": null,
    "intent": "commercial",
    "internalLinks": [
      "66fe91a2b3c4d5e6f7a8b9c0"
    ],
    "keyword": "headless cms pricing",
    "notes": "Use list prices from October 2026.",
    "outline": "Who each plan is for\nWhat it costs as you grow\nWhen to upgrade",
    "referenceUrls": [
      "https://example.com/cms-pricing-survey"
    ],
    "state": "ready",
    "wordCount": "1,500–2,000"
  },
  "category": {
    "description": "Guides to choosing and running a headless CMS.",
    "id": "6701c3d4e5f6a7b8c9d0e1f2",
    "name": "Headless CMS"
  },
  "clusterId": "6702d4e5f6a7b8c9d0e1f2a3",
  "dueDate": "2026-10-20",
  "id": "6704a1f0c2b3d4e5f6a7b8c9",
  "internalLinks": [
    {
      "id": "66fe91a2b3c4d5e6f7a8b9c0",
      "slug": "what-is-a-headless-cms",
      "title": "What is a headless CMS?"
    }
  ],
  "status": "idea",
  "title": "Headless CMS pricing",
  "version": 0
}

Replace a brief#

PUT/documents/:id/brief

Replaces the brief. Fields you leave out are cleared. The brief’s state doesn’t change. Returns the document.

Path parameters
idstringrequired
The document’s id.
Body
audiencestring | null
Who the document is for. At most 500 characters.
intentstring | null
The search intent: informational, commercial, transactional or navigational.
internalLinksstring[] | null
Ids of documents in this project to link to. At most 50, each at most 500 characters.
keywordstring | null
The keyword to rank for. At most 200 characters.
notesstring | null
Anything else the writer should know. At most 5,000 characters.
outlinestring | null
The outline as text, one section per line. At most 5,000 characters.
referenceUrlsstring[] | null
Sources to read, as http or https URLs. At most 50, each at most 500 characters.
wordCountstring | null
The target length as free text, such as 1,500–2,000. At most 50 characters.
Errors
BadRequest422
A field breaks a rule, such as an unknown intent, an internal link that isn’t a document in this project, or a reference URL that isn’t http or https.
NotFound404
No document with this id in the token’s project, or it was deleted.
curl -X PUT "https://api.pmkin.io/documents/6704a1f0c2b3d4e5f6a7b8c9/brief" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "audience": "Marketing leads comparing headless CMS plans",
  "intent": "commercial",
  "internalLinks": [
    "66fe91a2b3c4d5e6f7a8b9c0"
  ],
  "keyword": "headless cms pricing",
  "outline": "Who each plan is for\nWhat it costs as you grow\nWhen to upgrade",
  "wordCount": "1,500–2,000"
}'
Response: 200 OK
{
  "assigneeId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "authorId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "categoryId": "6701c3d4e5f6a7b8c9d0e1f2",
  "clusterId": "6702d4e5f6a7b8c9d0e1f2a3",
  "content": "",
  "contentUpdatedAt": "2026-10-08T09:12:44.000Z",
  "contentUpdatedBy": {
    "agent": "Claude Code",
    "id": "6703f6a7b8c9d0e1f2a3b4c5",
    "name": "Writing agent",
    "type": "token"
  },
  "coverImageUrl": null,
  "dueDate": "2026-10-20",
  "hasUnpublishedChanges": false,
  "id": "6704a1f0c2b3d4e5f6a7b8c9",
  "isPublished": false,
  "metaDescription": "",
  "metaTitle": "",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "publishedMarkdown": "",
  "publishedVersion": 0,
  "slug": "headless-cms-pricing",
  "status": "idea",
  "subtitle": "",
  "teamId": "66f0b2c4d5e6f7a8b9c0d1e1",
  "title": "Headless CMS pricing",
  "updatedAt": "2026-10-08T09:12:44.000Z",
  "version": 0,
  "wordCount": 0,
  "brief": {
    "audience": "Marketing leads comparing headless CMS plans",
    "claimedAt": null,
    "claimedBy": null,
    "intent": "commercial",
    "internalLinks": [
      "66fe91a2b3c4d5e6f7a8b9c0"
    ],
    "keyword": "headless cms pricing",
    "notes": "",
    "outline": "Who each plan is for\nWhat it costs as you grow\nWhen to upgrade",
    "referenceUrls": [],
    "state": "none",
    "wordCount": "1,500–2,000"
  }
}

Update a brief#

PATCH/documents/:id/brief

Changes the brief fields you send. null clears a field. Returns the document.

Path parameters
idstringrequired
The document’s id.
Body
audiencestring | null
Who the document is for. At most 500 characters.
intentstring | null
The search intent: informational, commercial, transactional or navigational.
internalLinksstring[] | null
Ids of documents in this project to link to. At most 50, each at most 500 characters.
keywordstring | null
The keyword to rank for. At most 200 characters.
notesstring | null
Anything else the writer should know. At most 5,000 characters.
outlinestring | null
The outline as text, one section per line. At most 5,000 characters.
referenceUrlsstring[] | null
Sources to read, as http or https URLs. At most 50, each at most 500 characters.
wordCountstring | null
The target length as free text, such as 1,500–2,000. At most 50 characters.
Errors
BadRequest422
A field breaks a rule, as for replace.
NotFound404
No document with this id in the token’s project, or it was deleted.
curl -X PATCH "https://api.pmkin.io/documents/6704a1f0c2b3d4e5f6a7b8c9/brief" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "notes": "Use list prices from October 2026."
}'
Response: 200 OK
{
  "assigneeId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "authorId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "categoryId": "6701c3d4e5f6a7b8c9d0e1f2",
  "clusterId": "6702d4e5f6a7b8c9d0e1f2a3",
  "content": "",
  "contentUpdatedAt": "2026-10-08T09:12:44.000Z",
  "contentUpdatedBy": {
    "agent": "Claude Code",
    "id": "6703f6a7b8c9d0e1f2a3b4c5",
    "name": "Writing agent",
    "type": "token"
  },
  "coverImageUrl": null,
  "dueDate": "2026-10-20",
  "hasUnpublishedChanges": false,
  "id": "6704a1f0c2b3d4e5f6a7b8c9",
  "isPublished": false,
  "metaDescription": "",
  "metaTitle": "",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "publishedMarkdown": "",
  "publishedVersion": 0,
  "slug": "headless-cms-pricing",
  "status": "idea",
  "subtitle": "",
  "teamId": "66f0b2c4d5e6f7a8b9c0d1e1",
  "title": "Headless CMS pricing",
  "updatedAt": "2026-10-08T09:12:44.000Z",
  "version": 0,
  "wordCount": 0,
  "brief": {
    "audience": "Marketing leads comparing headless CMS plans",
    "claimedAt": null,
    "claimedBy": null,
    "intent": "commercial",
    "internalLinks": [
      "66fe91a2b3c4d5e6f7a8b9c0"
    ],
    "keyword": "headless cms pricing",
    "notes": "Use list prices from October 2026.",
    "outline": "Who each plan is for\nWhat it costs as you grow\nWhen to upgrade",
    "referenceUrls": [
      "https://example.com/cms-pricing-survey"
    ],
    "state": "none",
    "wordCount": "1,500–2,000"
  }
}

Mark a brief ready#

POST/documents/:id/brief/ready

Offers the brief to agents: its state becomes ready and it shows up in GET /briefs. Works on a brief in none or drafted, on a document in idea, planned or drafting.

Path parameters
idstringrequired
The document’s id.
Errors
BriefClaimed409
Someone claimed the brief. Withdraw it first to offer it again.
BriefClosed409
The document is already in review, scheduled or published.
NotFound404
No document with this id in the token’s project, or it was deleted.
curl -X POST "https://api.pmkin.io/documents/6704a1f0c2b3d4e5f6a7b8c9/brief/ready" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"
Response: 200 OK
{
  "assigneeId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "authorId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "categoryId": "6701c3d4e5f6a7b8c9d0e1f2",
  "clusterId": "6702d4e5f6a7b8c9d0e1f2a3",
  "content": "",
  "contentUpdatedAt": "2026-10-08T09:12:44.000Z",
  "contentUpdatedBy": {
    "agent": "Claude Code",
    "id": "6703f6a7b8c9d0e1f2a3b4c5",
    "name": "Writing agent",
    "type": "token"
  },
  "coverImageUrl": null,
  "dueDate": "2026-10-20",
  "hasUnpublishedChanges": false,
  "id": "6704a1f0c2b3d4e5f6a7b8c9",
  "isPublished": false,
  "metaDescription": "",
  "metaTitle": "",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "publishedMarkdown": "",
  "publishedVersion": 0,
  "slug": "headless-cms-pricing",
  "status": "idea",
  "subtitle": "",
  "teamId": "66f0b2c4d5e6f7a8b9c0d1e1",
  "title": "Headless CMS pricing",
  "updatedAt": "2026-10-08T09:12:44.000Z",
  "version": 0,
  "wordCount": 0,
  "brief": {
    "audience": "Marketing leads comparing headless CMS plans",
    "claimedAt": null,
    "claimedBy": null,
    "intent": "commercial",
    "internalLinks": [
      "66fe91a2b3c4d5e6f7a8b9c0"
    ],
    "keyword": "headless cms pricing",
    "notes": "Use list prices from October 2026.",
    "outline": "Who each plan is for\nWhat it costs as you grow\nWhen to upgrade",
    "referenceUrls": [
      "https://example.com/cms-pricing-survey"
    ],
    "state": "ready",
    "wordCount": "1,500–2,000"
  }
}

Claim a brief#

POST/documents/:id/brief/claim

Claims a ready brief for the calling token and moves the document to drafting. The check and the write happen together, so when two agents claim at once, one wins and the other gets a 409 naming who claimed it and when. A claimed brief can’t be claimed again, even by the token that holds it.

Path parameters
idstringrequired
The document’s id.
Errors
BriefClaimed409
Someone already claimed it. Pick another brief from GET /briefs.
BriefNotReady409
The brief isn’t ready.
BriefClosed409
The document is already in review, scheduled or published.
NotFound404
No document with this id in the token’s project, or it was deleted.
curl -X POST "https://api.pmkin.io/documents/6704a1f0c2b3d4e5f6a7b8c9/brief/claim" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"
Response: 200 OK
{
  "assigneeId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "authorId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "categoryId": "6701c3d4e5f6a7b8c9d0e1f2",
  "clusterId": "6702d4e5f6a7b8c9d0e1f2a3",
  "content": "",
  "contentUpdatedAt": "2026-10-08T09:12:44.000Z",
  "contentUpdatedBy": {
    "agent": "Claude Code",
    "id": "6703f6a7b8c9d0e1f2a3b4c5",
    "name": "Writing agent",
    "type": "token"
  },
  "coverImageUrl": null,
  "dueDate": "2026-10-20",
  "hasUnpublishedChanges": false,
  "id": "6704a1f0c2b3d4e5f6a7b8c9",
  "isPublished": false,
  "metaDescription": "",
  "metaTitle": "",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "publishedMarkdown": "",
  "publishedVersion": 0,
  "slug": "headless-cms-pricing",
  "status": "drafting",
  "subtitle": "",
  "teamId": "66f0b2c4d5e6f7a8b9c0d1e1",
  "title": "Headless CMS pricing",
  "updatedAt": "2026-10-08T09:12:44.000Z",
  "version": 0,
  "wordCount": 0,
  "brief": {
    "audience": "Marketing leads comparing headless CMS plans",
    "claimedAt": "2026-10-07T10:04:00.000Z",
    "claimedBy": {
      "agent": "Claude Code",
      "id": "6703f6a7b8c9d0e1f2a3b4c5",
      "name": "Writing agent",
      "type": "token"
    },
    "intent": "commercial",
    "internalLinks": [
      "66fe91a2b3c4d5e6f7a8b9c0"
    ],
    "keyword": "headless cms pricing",
    "notes": "Use list prices from October 2026.",
    "outline": "Who each plan is for\nWhat it costs as you grow\nWhen to upgrade",
    "referenceUrls": [
      "https://example.com/cms-pricing-survey"
    ],
    "state": "claimed",
    "wordCount": "1,500–2,000"
  }
}

Withdraw a brief#

POST/documents/:id/brief/withdraw

Takes a ready brief back (its state becomes none), or releases a claimed one so it can be offered again. Over the REST API any token can release a claim; over MCP only the agent that claimed it can.

Path parameters
idstringrequired
The document’s id.
Errors
BriefNotOffered409
The brief isn’t ready or claimed.
NotFound404
No document with this id in the token’s project, or it was deleted.
curl -X POST "https://api.pmkin.io/documents/6704a1f0c2b3d4e5f6a7b8c9/brief/withdraw" \
  -H "Authorization: Bearer $PMKIN_MANAGEMENT_TOKEN"
Response: 200 OK
{
  "assigneeId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "authorId": "66f0b2c4d5e6f7a8b9c0d1f0",
  "categoryId": "6701c3d4e5f6a7b8c9d0e1f2",
  "clusterId": "6702d4e5f6a7b8c9d0e1f2a3",
  "content": "",
  "contentUpdatedAt": "2026-10-08T09:12:44.000Z",
  "contentUpdatedBy": {
    "agent": "Claude Code",
    "id": "6703f6a7b8c9d0e1f2a3b4c5",
    "name": "Writing agent",
    "type": "token"
  },
  "coverImageUrl": null,
  "dueDate": "2026-10-20",
  "hasUnpublishedChanges": false,
  "id": "6704a1f0c2b3d4e5f6a7b8c9",
  "isPublished": false,
  "metaDescription": "",
  "metaTitle": "",
  "projectId": "66f0b2c4d5e6f7a8b9c0d1e2",
  "publishedMarkdown": "",
  "publishedVersion": 0,
  "slug": "headless-cms-pricing",
  "status": "drafting",
  "subtitle": "",
  "teamId": "66f0b2c4d5e6f7a8b9c0d1e1",
  "title": "Headless CMS pricing",
  "updatedAt": "2026-10-08T09:12:44.000Z",
  "version": 0,
  "wordCount": 0,
  "brief": {
    "audience": "Marketing leads comparing headless CMS plans",
    "claimedAt": null,
    "claimedBy": null,
    "intent": "commercial",
    "internalLinks": [
      "66fe91a2b3c4d5e6f7a8b9c0"
    ],
    "keyword": "headless cms pricing",
    "notes": "Use list prices from October 2026.",
    "outline": "Who each plan is for\nWhat it costs as you grow\nWhen to upgrade",
    "referenceUrls": [
      "https://example.com/cms-pricing-survey"
    ],
    "state": "none",
    "wordCount": "1,500–2,000"
  }
}
Resources
GuidesBlogGlossaryPricingStatus page
Developers
Developer docsGitHubAngular CMSDjango CMSGatsby CMSNext CMSRails CMSReact CMSShopify CMSSvelte CMSVue CMS
Tools
GraphQL ValidatorThread CreatorWebsite to Markdown
Company
AboutPrivacyTerms of serviceCookies
Other
TwitterBuy me a coffee