Skip to Content
Skilder

REST API

Call Skilder from your own code over the public REST API.

In beta. The REST API can still change in ways that break an integration built on it today: an endpoint, a field or an error code can be renamed or removed.

The REST API manages the skills and roles of one workspace from your own code. Every request authenticates with an API key bound to that workspace.

Base URL

https://app.skilder.ai/api/v1

The version is part of the path. Every path on this page is relative to the base URL.

Authentication

Send a workspace API key as a bearer token:

Authorization: Bearer SKA_...

To create one, click your email at the bottom of the sidebar, choose Personal settings, open the API Keys tab and click Generate New Key. Pick the workspace, a description, the scopes and an expiry. The key is shown once: copy it before closing the dialog. See Profile and security.

A key acts as you, in its workspace only, and never beyond its scopes. A request that needs more than that is refused with 403.

The API accepts API keys only. Sign-in sessions and the OAuth tokens agents use over MCP are refused with 401.

Your first call

GET /me returns the user and workspace your key is bound to, with its scopes:

curl https://app.skilder.ai/api/v1/me \
  -H "Authorization: Bearer $SKILDER_API_KEY"
{
  "userId": "0x1a2b",
  "workspaceId": "0x3c4d",
  "key": {
    "displayPrefix": "SKA_xxxx",
    "scopes": ["read:skills"]
  }
}

Errors

Every error is an RFC 9457 problem details body, served as application/problem+json:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid, expired, or revoked API key.",
  "code": "UNAUTHENTICATED",
  "instance": "/api/v1/me"
}

Branch on code, not on detail. detail is for humans and can change.

StatuscodeMeans
400BAD_USER_INPUTThe request failed validation. errors lists each field with its message.
400BAD_REQUESTThe request is valid but cannot apply, for example an ownerId who is not an admin or contributor of the workspace.
401UNAUTHENTICATEDNo key, not an API key, or a key that is invalid, expired or revoked.
403FORBIDDENThe key is valid but may not do this. reason says why.
404NOT_FOUNDNo such resource in the key's workspace, or no such route.
409CONFLICTThe request conflicts with the resource's current state, for example a draft another user holds.
500INTERNAL_SERVER_ERRORThe server failed. detail never exposes internal errors.

The HTTP layer refuses a body that is not valid JSON, too large, or of the wrong content type. Those errors carry a code starting with FST_ERR_.

A 403 carries one of these reason values:

  • INSUFFICIENT_KEY_SCOPE: the key lacks the scope. Generate a key with a broader scope.
  • INSUFFICIENT_PERMISSIONS: your workspace role does not allow the action.
  • WORKSPACE_ACCESS_DENIED: you are no longer a member of the key's workspace.

A 409 on a draft carries a reason: DRAFT_LOCKED (another user holds the open draft) or NO_OPEN_DRAFT (there is no draft to act on).

Pagination

List endpoints take two query parameters:

ParameterValuesDefault
limit1 to 10020
cursorthe nextCursor of the previous pagefirst page

They answer with the same envelope:

{
  "data": [],
  "pagination": { "limit": 20, "nextCursor": "bzE6MjA" }
}

nextCursor is null on the last page. Pass it back unchanged and never parse it: its encoding is not part of the API.

OpenAPI document

The full contract is an OpenAPI 3.1 document, served without authentication at https://app.skilder.ai/api/v1/openapi.json. Point your client generator at it.

On this page