API documentation

NudgeHost has two public interfaces. The v1 REST API uploads files and manages the links they produce, and the MCP server exposes the same account to an AI client as four tools. Both authenticate with the same API key.

1. Authentication

Every request carries a bearer token. There is no session cookie and NudgeHost checks no scopes, so whichever credential you send grants the whole of one account.

authenticated request
bash
curl https://www.nudgehost.com/api/v1/files \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY"

The key above is a placeholder rather than a working credential. Yours comes from the dashboard.

Two kinds of credential

An API key is the short path. You create one in the dashboard, paste it into your client, and everything below applies unchanged. Use it for your own scripts, your CI, and anything running on your own account.

An OAuth access token is for software acting on somebody else's behalf, where asking them to paste a key would be the wrong shape. NudgeHost is an OAuth 2.0 protected resource and publishes the RFC 9728 document naming the authorization server that issues those tokens. A client that meets a 401 here can read the resource_metadata parameter on the challenge, fetch the document it names, and register itself without anybody configuring it by hand. The MCP endpoint's challenges name a document of its own, at the same address followed by /api/mcp.

Both arrive the same way, in the Authorization header as a bearer token, and the rest of this page does not distinguish them. The rate limits in section 3 apply to both, counted per key for a key and per account for a token.

The key format

A key is 49 characters long. It opens with the fixed marker nh_sk_ and continues with 43 base64url characters carrying 256 bits of randomness. The marker is fixed so that a leaked key is recognisable on sight, and so that credential scanners have a pattern to match.

The scheme name is matched case-insensitively, so Bearer and bearer both work, and any run of spaces or tabs may separate the scheme from the key. The key itself must contain no whitespace.

Generating a key

Keys are created in the API keys panel of your dashboard. If you are signed out, the link asks you to sign in first and then opens the panel. Give each key a name of up to 60 characters so you can tell them apart later, then create it.

The key is displayed once, at the moment it is created. What NudgeHost stores is a SHA-256 hash of it, so the original string cannot be recovered afterwards by you or by us. Copy it somewhere safe before you close the panel. If a key is lost, revoke it and create another.

After that, the dashboard shows the first 12 characters of each key so you can tell two of them apart, and holds back the remaining 37.

How many keys a plan holds

Every plan can use the API, including the free one. What varies is how many keys an account may hold at once.

  • Free: 1 key, or 2 on a free account made before 12 November 2026
  • Lite: 2 keys
  • Pro: 10 keys
  • Studio: 30 keys

Revoking a key frees its slot straight away. Full plan details are on the pricing page.

2. The host rule

Send every request to www.nudgehost.com. That host is canonical and it is where the API answers.

The apex, nudgehost.com, answers 308 and points at the www host. That redirect crosses an origin boundary, so HTTP clients drop the Authorization header while following it. The request then arrives with no credential at all and is refused with 401 and the code unauthorized, which reads exactly like a bad key. If a key you know is good keeps coming back unauthorized, check the host before you rotate anything.

host matters
bash
# Wrong host. The apex answers 308 and redirects to www, and the
# Authorization header does not survive that hop, so this arrives
# with no credential and comes back 401 unauthorized.
curl -L https://nudgehost.com/api/v1/files \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY"

# Right host. Send every request straight to www.
curl https://www.nudgehost.com/api/v1/files \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY"

A client that does not follow redirects sees the 308 itself rather than the 401. Either way the call does not do what you asked, and pointing at www is the whole fix.

3. Rate limits

Each key gets a fixed number of requests per 60 second window, set by the account's plan.

  • Free: 20 requests per 60 seconds
  • Lite: 20 requests per 60 seconds
  • Pro: 60 requests per 60 seconds
  • Studio: 150 requests per 60 seconds

The budget belongs to the key rather than to the account or to the calling IP address. Two keys on one account therefore have independent budgets, and one script exhausting its own key leaves the other key untouched. Splitting a noisy job onto its own key is a reasonable way to keep it away from everything else.

A request authenticated with an OAuth access token is counted against the account instead, at the same rate for the same plan. Tokens are minted and rotated by the authorization server rather than created by hand, so there is no stable per-credential thing to count against. Every integration a person has authorized shares that one budget.

Going over returns 429 with the code rate_limited and a Retry-After header. That header carries the full window, 60 seconds, rather than a countdown to the moment a slot frees up. Treat it as an upper bound. Waiting it out always works, and a slot often opens sooner.

429 response
http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Cache-Control: private, no-store
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests in the last minute. The free plan allows 20 a minute, and Pro allows 60. See https://www.nudgehost.com/pricing.",
    "details": { "retryAfterSeconds": 60 }
  }
}

4. Errors

Every failure arrives in the same envelope, with a machine-readable code beside a sentence written for a person. The details object is present only where a client needs a value it would otherwise have to read out of the sentence, such as the byte ceiling a file just exceeded or the name of the field that failed.

404 response
http
HTTP/1.1 404 Not Found
Cache-Control: private, no-store
Content-Type: application/json

{
  "error": {
    "code": "not_found",
    "message": "That file is gone or was never on your account."
  }
}

Switch on error.code rather than on the status or the wording. Several distinct failures share a status, and the wording is free to change. Each code maps to exactly one status, so the same code never arrives as a 400 from one endpoint and a 422 from another.

CodeStatusMeaning
unauthorized401No Authorization header arrived, or it was not a bearer credential.
invalid_key401A key arrived and did not resolve. Malformed, unknown, and revoked all give this one answer, so the endpoint cannot be used to learn which.
invalid_token401An OAuth access token arrived and did not verify. Expired, revoked, and never a token at all give this one answer, on the same reasoning as invalid_key.
rate_limited429The credential has used up its window, counted per key for a key and per account for an access token. Carries Retry-After.
invalid_request400A body field or query parameter is missing, malformed, or the wrong type. Where there is a single culprit, details.field names it.
not_found404No such resource for this caller. A file that never existed and a file belonging to somebody else give the same answer on purpose. A request to a path with no endpoint behind it answers the same way, so a typo in a URL reads as this code rather than as a page.
file_too_large413Over the plan's per-file ceiling. details carries maxBytes and plan.
link_limit_reached403The account is at its active-link cap.
account_blocked403The account has been blocked for abuse and may not create files. The key still authenticates, and listing and deleting still work.
upload_incomplete422The bytes never arrived in storage. The upload is removed, so start a new one.
upload_rejected422The bytes arrived and cannot be used. The archive may be unsafe, or a site that unpacks past the plan ceiling, holds more than 200 files or cannot be read. The message gives the specific reason, and the upload is removed.
method_not_allowed405Right path, wrong verb.
internal_error500Our fault. Reported before the response is sent.

That list of codes is closed. A new one would be a breaking change and will not appear without a version change, so a client may treat an unrecognised code as a bug rather than as something to handle.

The kind field on a file is the opposite. It is not a closed set, because the column behind it is unconstrained text. Treat it as a string and leave a path for a value you do not recognise rather than switching over it exhaustively. The four values the code produces today are file, docx, site, and paste.

5. The REST endpoints

Five endpoints, all under /api/v1. Every id, slug and URL in the samples below is a placeholder. Yours come back in the responses.

Each path answers one verb. The others are wired to a refusal rather than left to fall through, so a POST to a listing endpoint returns 405 with the code method_not_allowed and the message That method is not supported on this endpoint. A 404 from one of these paths always means the resource, never the verb.

POST /api/v1/uploads

Reserves a link and returns a signed URL to send the bytes to. This creates the row. Nothing serves until you complete the upload in the next call.

The JSON body takes four fields.

  • filename (required), the name to store the file under, including its extension.
  • contentType (required), the MIME type of the bytes.
  • fileSize (required), the exact byte count you are about to send, as a number.
  • desiredSlug (optional), a preferred short name for the link. It is cleaned up and checked on the server. One that is taken or unusable is replaced with a random one rather than failing the call, so read the slug back out of the response. A free account made from 12 November 2026 always gets a random name, so the field is ignored there.
start an upload
bash
curl -X POST https://www.nudgehost.com/api/v1/uploads \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "report.pdf",
    "contentType": "application/pdf",
    "fileSize": 182734
  }'
201 response
http
HTTP/1.1 201 Created

{
  "id": "00000000-0000-0000-0000-000000000000",
  "slug": "example1",
  "url": "https://www.nudgehost.com/example1",
  "upload": {
    "url": "https://EXAMPLE-BUCKET.r2.cloudflarestorage.com/files/EXAMPLE/report.pdf?X-Amz-Signature=EXAMPLE_NOT_A_REAL_SIGNATURE",
    "method": "PUT",
    "expiresInSeconds": 300,
    "headers": {
      "Content-Type": "application/pdf",
      "Content-Length": "182734"
    }
  }
}

Answers 201 on success. It can also return 400 invalid_request, 401, 403 link_limit_reached or account_blocked, 413 file_too_large, 429, and 500. The link_limit_reached 403 reaches Free and Lite accounts at their active-link cap, account_blocked means the account may not upload, and the 413 arrives when fileSize is over the plan ceiling, with details.maxBytes naming the limit.

POST /api/v1/uploads/{id}/complete

Turns the reserved row into a working link, once the bytes have landed. Takes no body. The id is the one from the start call.

complete an upload
bash
curl -X POST \
  https://www.nudgehost.com/api/v1/uploads/00000000-0000-0000-0000-000000000000/complete \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY"
200 response
http
HTTP/1.1 200 OK

{
  "id": "00000000-0000-0000-0000-000000000000",
  "slug": "example1",
  "url": "https://www.nudgehost.com/example1",
  "kind": "file",
  "filename": "report.pdf",
  "mimeType": "application/pdf",
  "fileSize": 182734,
  "createdAt": "2026-08-17T17:23:11.572Z"
}

Answers 200 on success. It can also return 401, 403, 404, 422, 429, and 500. The 403, with the code link_limit_reached, means a Free or Lite account reached its active-link cap while the upload was in flight. The cap is counted again as an upload finishes, and an upload holds its place for only an hour after it starts. The upload is removed, so start a new one once the account has room. The 422 covers two cases. The code upload_incomplete means the bytes never arrived. The upload is removed when that happens, so the id cannot be completed again. Start a new upload from step 1. The code upload_rejected means the bytes arrived and cannot be used, with the specific reason in the message. A ZIP becomes a site, with its own address, when it holds a file named index.html and is 100MB or smaller. A ZIP without an index.html, or over 100MB, stays a download.

Read the url out of this response rather than reusing the one from step 1. An HTML page has its own nudgehost.site address from the start. A ZIP that unpacks into a site moves to its own address, so the final URL can differ from the one the start call predicted.

GET /api/v1/files

Lists the account's files, newest first. Takes three optional query parameters.

  • limit, a whole number from 1 to 100. Defaults to 50.
  • cursor, the nextCursor from the previous page.
  • includeDeleted, set to the string true to include soft-deleted files.
list files
bash
curl "https://www.nudgehost.com/api/v1/files?limit=25" \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY"
200 response
http
HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "slug": "example1",
      "filename": "report.pdf",
      "fileSize": 182734,
      "mimeType": "application/pdf",
      "kind": "file",
      "viewCount": 2,
      "createdAt": "2026-08-17T17:23:11.572Z",
      "expiresAt": null,
      "url": "https://www.nudgehost.com/example1",
      "hasPassword": false,
      "isDeleted": false
    }
  ],
  "nextCursor": "EXAMPLE_OPAQUE_CURSOR_VALUE"
}

Answers 200 on success, and can also return 400 invalid_request, 401, 429, and 500.

GET /api/v1/files/{id}/opens

How many times one link has been opened. On Free and Lite the answer carries the count only, with detail set to count and no opens key. On Pro and Studio, detail is opens and the answer lists the 100 most recent opens, newest first.

Each open gives its time in UTC and its country, as a two-letter code and an English name, either of which is null when the country was not known. Nothing identifies who opened the link, because NudgeHost records no name, email address or IP address for an open. Link-preview and search crawlers are never counted, so they are not in the list or the count.

read a link's opens
bash
curl https://www.nudgehost.com/api/v1/files/00000000-0000-0000-0000-000000000000/opens \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY"
200 response, Pro or Studio
http
HTTP/1.1 200 OK

{
  "id": "00000000-0000-0000-0000-000000000000",
  "slug": "example1",
  "filename": "report.pdf",
  "url": "https://www.nudgehost.com/example1",
  "viewCount": 2,
  "expiresAt": null,
  "isDeleted": false,
  "detail": "opens",
  "opens": [
    {
      "openedAt": "2026-08-18T09:12:40.118Z",
      "country": "DE",
      "countryName": "Germany"
    },
    {
      "openedAt": "2026-08-17T18:02:05.904Z",
      "country": null,
      "countryName": null
    }
  ]
}

Answers 200 on success, and can also return 401, 404, 429, and 500. A deleted link still answers, with isDeleted true, because its count survives deletion.

DELETE /api/v1/files/{id}

Deletes one file. The delete is soft, so the row survives and the slug stays taken, while the link stops serving.

delete a file
bash
curl -X DELETE \
  https://www.nudgehost.com/api/v1/files/00000000-0000-0000-0000-000000000000 \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY"
200 response
http
HTTP/1.1 200 OK

{
  "id": "00000000-0000-0000-0000-000000000000",
  "deleted": true
}

Answers 200 on success, and can also return 401, 404, 429, and 500. This call is not idempotent. Deleting the same id twice returns 404 the second time, and a client retrying after a timeout on a call that actually succeeded cannot tell that answer apart from a file that never existed.

Deleting the file also removes its custom domain. The domain stops serving at once and no longer counts against the account's domain allowance. To use it again, add it to another link in the dashboard.

6. The upload flow end to end

Publishing a file takes three calls. The link does not serve anything until all three have happened.

Step 1. Start the upload

POST the filename, content type and exact byte count to /api/v1/uploads. The response carries the file id you will need in step 3, and an upload object holding the URL to send the bytes to.

That URL is signed and it expires. You have 300 seconds to use it, which the response repeats as expiresInSeconds. If it lapses before the bytes land, start again for a fresh URL rather than reusing the id.

Step 2. PUT the bytes

send the bytes
bash
# The URL, the method and both header values come from the
# upload object in step 1. Send them as given.
curl -X PUT "https://EXAMPLE-BUCKET.r2.cloudflarestorage.com/files/EXAMPLE/report.pdf?X-Amz-Signature=EXAMPLE_NOT_A_REAL_SIGNATURE" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

The signature covers the byte count and the host. A body whose length is anything other than the fileSize you declared is refused by storage rather than by us.

Content-Type is not covered by that signature, so storage accepts a PUT whose Content-Type disagrees with what you declared, and nothing fails at this step. The type the link serves under is decided when you complete the upload. NudgeHost reads the first bytes of the file and weighs them against the contentType from step 1 and the filename. A recognised file signature, such as a PDF or PNG header, wins over the declared type. HTML is kept as HTML only when you declared text/html. An image, PDF, HTML or ZIP type with no matching signature behind it is stored as application/octet-stream. Otherwise the declared type stands, so send the true type in step 1.

Step 3. Complete the upload

complete the upload
bash
curl -X POST \
  https://www.nudgehost.com/api/v1/uploads/00000000-0000-0000-0000-000000000000/complete \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY"

Completing is idempotent. Calling it a second time on a file that is already complete returns the same 200 and the same body rather than an error, and destroys nothing, so a retry after a dropped connection is safe.

7. Pagination

The listing endpoint pages with a cursor. Ask for a page, and when more files exist the response carries a nextCursor to send back for the one after it. On the last page nextCursor is null.

limit takes a whole number from 1 to 100, and leaving it out gives you 50. Anything outside those bounds returns 400 with the code invalid_request and details.field set to limit.

The cursor is opaque. Pass back exactly the value you were given rather than one you build, since its format is not part of the contract. A cursor that does not decode returns 400 with the code invalid_request and details.field set to cursor, with the message cursor is not one we issued. Send back the nextCursor from the previous page.

page through every file
bash
cursor=""
while :; do
  url="https://www.nudgehost.com/api/v1/files?limit=100"
  if [ -n "$cursor" ]; then
    url="$url&cursor=$cursor"
  fi

  page=$(curl -s "$url" -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY")
  echo "$page" | jq -r '.data[].url'

  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
  # An absent or null nextCursor is the last page.
  [ -z "$cursor" ] && break
done

That loop uses jq to read fields out of each response. If you do not have it installed, what you get is a command-not-found error from your shell rather than anything from NudgeHost.

One trap worth knowing about. includeDeleted accepts the exact string true and nothing else. The values 1, TRUE and yes are all read as false, and none of them is an error, so a request carrying one comes back 200 with deleted files quietly missing.

8. The MCP server

This section is not covered by the OpenAPI document. That document describes the REST API and nothing else, so a client generated from it will not have any of the tools below. Read this section rather than the schema if you are wiring up an AI client so it can share files for you through MCP.

Endpoint and transport

The server lives at POST https://www.nudgehost.com/api/mcp. It speaks revision 2026-07-28 of the Streamable HTTP transport, and also the earlier revisions 2025-11-25 and 2025-06-18 for clients that open with an initialize request. POST is the only verb it answers. Anything else returns 405.

The transport is stateless. On 2026-07-28 there is no initialize handshake, no session id, no standalone GET stream, and no resumability. A client on 2025-11-25 or 2025-06-18 opens with initialize and gets no session id back, then sends the version it was given in the MCP-Protocol-Version header on every request after that. On either path the server remembers nothing between two requests. Every reply is a single JSON object sent as application/json. The server never opens an event stream, and a client that sends no Accept header is not refused over it.

Because nothing is remembered, each 2026-07-28 request has to carry its own context. Three headers matter.

  • MCP-Protocol-Version on every request, matching the version inside the body.
  • Mcp-Method on every request, matching the body's method.
  • Mcp-Name on tools/call, matching params.name.

The body repeats two of those facts under params._meta, which must carry io.modelcontextprotocol/protocolVersion as a string and io.modelcontextprotocol/clientCapabilities as an object. An empty object is fine. A header that is missing or that disagrees with the body returns 400, since a mismatch between what a gateway routes on and what the server executes is the shape of an attack rather than a typo worth guessing at.

call a tool
bash
curl -X POST https://www.nudgehost.com/api/mcp \
  -H "Authorization: Bearer nh_sk_REPLACE_WITH_YOUR_OWN_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: list_links" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_links",
      "arguments": { "limit": 10 },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Connecting a client

The Claude Code, Cursor and Codex CLI setups below name an environment variable, NUDGEHOST_API_KEY, rather than the key itself, so the key stays out of the config file. Set that variable to an API key from your dashboard, then start or restart the client so it reads the new value.

Claude Code. Put this in .mcp.json in the folder you start Claude Code from. Tested 13 October 2026, on its default runtime and with MCP_PROTOCOL_NEGOTIATION set to legacy.

.mcp.json
json
{
  "mcpServers": {
    "nudgehost": {
      "type": "http",
      "url": "https://www.nudgehost.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${NUDGEHOST_API_KEY}"
      }
    }
  }
}

Cursor. Add this entry to ~/.cursor/mcp.json, which Cursor reads for every project. Tested 13 October 2026.

~/.cursor/mcp.json
json
{
  "mcpServers": {
    "nudgehost": {
      "url": "https://www.nudgehost.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NUDGEHOST_API_KEY}"
      }
    }
  }
}

Codex CLI. Add this table to ~/.codex/config.toml. It needs no feature flag. Tested 13 October 2026.

~/.codex/config.toml
toml
[mcp_servers.nudgehost]
url = "https://www.nudgehost.com/api/mcp"
bearer_token_env_var = "NUDGEHOST_API_KEY"

Claude. Connect NudgeHost from its page in Claude's connector directory, where it carries Anthropic's Community label and Claude shows a reminder before connecting. To add NudgeHost to Claude as a custom connector instead, open Customize, then Connectors. Choose Add, then Add custom connector, give it a name such as NudgeHost, enter https://www.nudgehost.com/api/mcp and choose Continue. Keep the sign-in settings Claude finds, then choose Add. On Team and Enterprise plans, an owner adds it first, under Organization settings, then Connectors, and each member then connects it from Customize, then Connectors. Claude sends you to NudgeHost to sign in and approve its access, then brings you back with NudgeHost connected. This setup needs no API key, because Claude holds an access token for your account instead.

Tested 31 October 2026, for publishing a note with share_text and for listing links with list_links. Uploading a file needs a client that can send the file itself to the upload URL, such as Claude Code. In that test, Claude's sandbox could not reach NudgeHost's storage, so the upload published nothing.

Authentication, host, and rate limits

Authentication works as it does for the REST API in section 1. Claude Code, Cursor and Codex send an API key as a bearer token, and Claude sends the access token it received when you signed in. The host rule in section 2 applies here too, so send requests to www rather than to the apex.

The rate limit is the same per-key budget from section 3, and the two interfaces share it rather than getting one each. A key that has spent its window on REST calls has nothing left for MCP calls in that window, and the reverse. Splitting the two onto separate keys gives them separate budgets. A client that signs in, such as Claude, gets one budget per account instead, shared by every app signed in to it.

The tools

Four tools, listed here in the order tools/list returns them. The schemas each tool publishes are advisory. Every handler validates its own input, so a call that satisfies the published schema can still be refused, and the message says why.

share_text

Publishes text as a file and returns the link, in one call. A filename ending in .html or .htm produces a page the recipient reads in the browser. A .csv or .json file opens in the table or JSON viewer. A .md or .markdown file shows as formatted text, with a Source view and a Copy source button, and HTML inside it shows as typed. Any other filename shows the text as plain text, with a Copy text button. The .md and plain text results also serve the raw text at the link plus /raw. Content is capped at 2MB, measured in UTF-8 bytes rather than in characters, so text with accents or emoji reaches the cap sooner than its length suggests.

  • filename (required), the name to give the file, including an extension.
  • content (required), the text to publish. May be empty.

create_upload_url

Starts an upload for a file the server does not hold, and returns the URL to send the bytes to. This is the MCP form of step 1 in section 6, and the same rules apply, including the 300 second expiry and the Content-Type behaviour.

  • filename (required).
  • content_type (required), the MIME type of the bytes.
  • size_bytes (required), a whole number, the exact byte count.
  • desired_slug (optional), a preferred short name. One that is taken or unusable is replaced rather than failing the call, and a free account made from 12 November 2026 always gets a random name.

complete_upload

Finishes an upload that create_upload_url started, once the bytes have been sent. This is step 3 in section 6, with the same behaviour, including that calling it twice is safe.

  • id (required), the id create_upload_url returned.

list_links

Lists the account's links, newest first. Deleted links are never included. Both fields are optional, and a call with no arguments is the ordinary way to use it.

  • limit (optional), a whole number from 1 to 100. Leaving it out gives you 50.
  • cursor (optional), the cursor from the end of a previous reply. Pass back exactly the value you were given.

This tool publishes its own bounds rather than sharing the REST endpoint's, and the two currently hold the same numbers. Treat section 7 as describing both.

Auth errors

A refused credential comes back as a JSON-RPC error rather than in the REST envelope, because an MCP client parses JSON-RPC and would read the other shape as a malformed response. Three codes cover it, all at HTTP 401.

  • -31001, no credential arrived. Send the key as a bearer token.
  • -31002, a key arrived and did not resolve. Malformed, unknown, and revoked give this one answer.
  • -31006, an access token arrived and did not verify. Expired, revoked and malformed tokens give this one answer. Sign in to the integration again to get a new one.

A request over the rate limit comes back as -31003 at HTTP 429, with the wait in seconds in data.retryAfterSeconds and in a Retry-After header.

None of these responses echoes a request id, so match them to your request by the fact that they arrived rather than by the id you sent.