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/v1The 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.
| Status | code | Means |
|---|---|---|
400 | BAD_USER_INPUT | The request failed validation. errors lists each field with its message. |
400 | BAD_REQUEST | The request is valid but cannot apply, for example an ownerId who is not an admin or contributor of the workspace. |
401 | UNAUTHENTICATED | No key, not an API key, or a key that is invalid, expired or revoked. |
403 | FORBIDDEN | The key is valid but may not do this. reason says why. |
404 | NOT_FOUND | No such resource in the key's workspace, or no such route. |
409 | CONFLICT | The request conflicts with the resource's current state, for example a draft another user holds. |
500 | INTERNAL_SERVER_ERROR | The 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:
| Parameter | Values | Default |
|---|---|---|
limit | 1 to 100 | 20 |
cursor | the nextCursor of the previous page | first 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.

