API overview - Valendata

The Valendata API lets you create, run, schedule, and improve skills and workflows from your own code. Everything an AI assistant can do through MCP tools is also here, under the same names.

Base URL

https://api.valendata.com/v1

Send JSON with Content-Type: application/json. Every response is JSON.

Resources and naming

Every resource uses the same verbs:

You want to	Method	Page title starts with	MCP tool starts with
See many	`GET /v1/<resource>`	List	`list_`
See one	`GET /v1/<resource>/{id}`	Get	`get_`
Make one	`POST /v1/<resource>`	Create	`create_`
Change one	`PATCH /v1/<resource>/{id}`	Update	`update_`
Remove one	`DELETE /v1/<resource>/{id}`	Delete	`delete_`

Skills and workflows are named by their slug. Runs and schedules by their id.

Resource	Routes
Skills	`/v1/skills`, `/v1/skills/{slug}`, `/v1/skills/{slug}/health`, `/v1/skill-creations`, `/v1/skill-creations/{creation_id}`
Runs	`/v1/skills/{slug}/run` (wait), `/v1/skills/{slug}/runs` (background, and list), the same under `/v1/workflows/{slug}`, and `/v1/runs/{run_id}` for any run
Skill versions	`/v1/skills/{slug}/versions`, `/v1/skills/{slug}/pin`
Improvements	`/v1/skills/{slug}/improve`, `/v1/skills/{slug}/improvements`, `/v1/skill-improvements/{improvement_id}`
Schedules	`/v1/schedules`, `/v1/schedules/{schedule_id}`, `/v1/skills/{slug}/schedules`, `/v1/workflows/{slug}/schedules`
Workflows	`/v1/workflows`, `/v1/workflows/{slug}`
Logins	`/v1/logins`, `/v1/logins/{login_id}`
Account and usage	`/v1/account`, `/v1/usage`
Webhooks	`/v1/webhooks/secret`

Two run routes differ by one letter on purpose: /run waits for the result, /runs starts in the background. See Runs.

Conventions

Field names are snake_case. Timestamps are ISO 8601 in UTC with a Z, such as 2026-10-06T18:37:00Z.
Ids are opaque strings. Most carry a prefix that says what they are (skl_, sklsch_, wfsch_); some older ones (workflows, logins, workflow runs) are plain UUIDs. Never parse an id; store it as you got it.
Credit amounts on Account and usage are decimal strings with two places ("3500.43"), so no precision is lost; credits.balance_number has the balance as a number. Run costs (credits, credits_charged) are numbers.
Booleans are JSON true and false. Enum values are listed on each route’s page.
Every response carries X-Request-ID. Every error has the same body. See Errors and limits.
The full OpenAPI document is at https://api.valendata.com/v1/openapi.json. Each operation’s operationId is the name of the MCP tool that does the same thing (list_skills, create_workflow, run_skill); x-mcp-tool names the tool where it differs.

Versioning and deprecation

The version is in the path: /v1. Within v1, changes are additive only: new routes, new optional parameters, new response fields, new error code values. Write your client to ignore fields it does not know. A route that will go away is marked deprecated in the reference and answers with three headers, for at least six months before it is removed:

Deprecation: @1791244800
Sunset: Tue, 06 Apr 2027 00:00:00 GMT
Link: <https://docs.valendata.com/api-reference/runs/run-skill>; rel="successor-version"

Deprecation is when it was deprecated (Unix time), Sunset is the earliest date it may be removed, and Link points to the route to use instead. Deprecated today:

Route	Use instead
`POST /v1/skills/run` (run by id)	`POST /v1/skills/{slug}/run`
`GET /v1/workflow-runs/{run_id}`	`GET /v1/runs/{run_id}`

The rest of the basics

Each of these has one page:

Authentication and scopes

Send your key. What each scope allows.

Errors and limits

Status codes, error bodies, rate limits, and runs in progress.

Pagination and idempotency

Page through lists. Retry safely.

Webhooks

Get finished runs pushed to you, and verify them.

​Base URL

​Resources and naming

​Conventions

​Versioning and deprecation

​The rest of the basics