One workspace, over HTTP.

Mint a token at Settings, API inside the product, then ask the API what it can see. If this returns your accounts, everything else on this page will work.

curl -H "Authorization: Bearer $TOKEN" https://crestnote.com/api/v1/accounts

Every response is JSON. Success and failure are distinguishable by shape alone: a failure has a top-level error object and a success never does, so a client can write if ('error' in body) and never consult a status code. That matters more than it sounds, because a proxy or a corporate middlebox can rewrite a status and none of them rewrites a body.

GET https://crestnote.com/api/v1 with no token returns the list of endpoints, so you can check the base URL is right before you have a credential.

A bearer token, in a header. Nothing else is accepted, and in particular there is no ?token= query parameter: a credential in a URL lands in every access log, every proxy and every browser history between you and us, and the convenience of putting it there is exactly why people do it by accident.

Authorization: Bearer sk_social_xxxxxxxxxxxx

A token belongs to one workspace and carries one role. A member token reads. An admin token also writes: creating, changing and cancelling posts. A token can never outrank the person who created it, so a member of a workspace cannot mint an admin token.

The plaintext is shown once, when it is created, and is never recoverable: we store a hash of it and nothing else. If one leaks, revoke it. Revocation takes effect on the next request.

A missing token, an unknown one and a revoked one are all answered with the same 401 and the same sentence. That is deliberate: telling them apart confirms to somebody holding a string from an old log that it was once real.

Every failure has the same shape. Branch on code, which is stable forever. Never match on message, which is written for a human reading a log at 3am and is improved whenever a better sentence exists.

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "A post needs content.",
    "param": "content",
    "request_id": "req_9f2c41ab8e5d4c7a"
  }
}

type says what to do rather than what went wrong, which is the distinction a retry loop needs and a status code does not give you: invalid_request_error and authentication_error mean stop and fix it, api_error means waiting is reasonable.

request_id is on every response, failures and successes, in the body and in the X-Request-Id header. Quote it and a support conversation is one message long, because it is in our log beside whatever produced it.

Every list takes limit (1 to 200, default 50) and cursor, and returns the same envelope.

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOC0xN1QwOTowMDowMFogYTFiMg"
}

Read until has_more is false, passing the previous next_cursor back as ?cursor=. Cursors are opaque; decoding one reveals nothing you were not just sent, but constructing one by hand is not supported and the format will change.

cursor=""
while : ; do
  page=$(curl -s -H "Authorization: Bearer $TOKEN" "https://crestnote.com/api/v1/posts?limit=200&cursor=$cursor")
  echo "$page" | jq '.data[]'
  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.next_cursor')
done

It is a cursor and not ?page= because these lists are ordered newest first and rows arrive at the front of them constantly: a cron writes metrics every few minutes and the queue writes posts all day. With offsets, a caller reading page two after three new rows arrived sees three rows they already read, and one reading while rows are deleted skips some entirely.

Per token, per minute: 300 reads and 60 writes. Writes are lower because a runaway write loop publishes to a real audience, and the thing being protected there is your account rather than our database.

Every response carries your budget, so a well-behaved client never has to guess:

RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 34

Over the limit is a 429 with Retry-After in seconds. If one integration needs more headroom, mint it a second token: the limit is keyed to the token, so an export and a live agent on the same workspace do not compete, and revoking a runaway one restores everybody else’s budget immediately.

Send Idempotency-Key on every write. Any unique string per logical operation will do, and a UUID is the usual choice.

curl -X POST https://crestnote.com/api/v1/posts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"accountIds":["..."],"content":"Hello"}'

A repeat of the same key returns the first response verbatim, with Idempotent-Replay: true on it, and does no work. Keys live 24 hours.

This is not politeness. Your client retries a request whose response was lost, because from where it is standing the request never happened, and the request may well have succeeded. Without a key, that retry publishes the same post twice and your followers are the ones who notice.

Reusing a key with a different body is refused with idempotency_conflict rather than replayed. Replaying would hand you the first post’s id for a request that asked for something else, and you would believe the second one was queued.

Worth its own section because it will change how you write your client. Where a platform did not report a metric, the field is null. It is never coalesced to 0 on the way in and never on the way out.

Some networks never report some metrics at all, and every network occasionally fails to answer. A zero in place of either is a fabricated measurement, and the conclusion drawn from it (“engagement fell to nothing on the 14th”) is one nobody made. Chart a null as a gap in the line and average over the readings you have.

The same rule applies to competitor text: title and excerpt on /rivals/posts are null on older rows, because the counts are kept while the platform’s words about somebody else are purged on a retention clock. An absent excerpt is a normal row and never a missing post. The permalink is always there.

The version is in the path, and v1 is the only one. Inside it, these are additive and can happen at any time: a new endpoint, a new field on a response, a new optional parameter, a new value in an enum, a new error code. Write a client that ignores fields it does not recognise.

These would be a new version rather than a change to this one: removing or renaming a field, changing the type of one, removing an endpoint, changing what an existing code means, or making an optional parameter required.

If v2 is ever needed, v1 keeps working for at least twelve months after it is announced, and the announcement goes to the email on every workspace using a token rather than only onto the changelog.

13 of them. Every path below is relative to https://crestnote.com/api/v1, every one needs a token, and the role each needs is on its heading.

The same operations, spoken to by an agent instead of a script. Point any MCP client at the endpoint with the same token in the same header.

{
  "mcpServers": {
    "social": {
      "url": "https://crestnote.com/api/mcp",
      "headers": { "Authorization": "Bearer $TOKEN" }
    }
  }
}

It speaks JSON-RPC 2.0 over a single POST: initialize, tools/list and tools/call. There is deliberately no SSE stream, no notifications, no sampling and no resources, because each needs server state a serverless deployment does not have, and a capability claimed and then unanswered reads as a broken server rather than a smaller one.

Each tool calls the same function its REST endpoint calls, so an agent and a script cannot see different rows of the same workspace.