Valendata REST API Reference — Overview and Quick Start

The Valendata REST API gives you programmatic access to every resource on the platform — Skills, Workflows, Runs, Browser Profiles, and more. Every request and every response uses JSON, and all communication happens over HTTPS.

Base URL

Valendata uses two path prefixes depending on the operation:

/v1/skills — Skill execution endpoints (run a Skill, run by slug)
/api/* — All other resources: Workflows, Browser Profiles, credentials, API key management, and Marketplace

For example:

POST https://api.valendata.com/v1/skills/run
POST https://api.valendata.com/api/workflows/{workflow_id}/run

Request & Response Format

Every request body must be JSON, and every response body is JSON. Set the Content-Type header to application/json on all requests that include a body.

Content-Type: application/json

Successful responses return the requested data at the top level of the JSON object. The exact shape of each response is documented on the relevant endpoint page.

Authentication

Every request to the Valendata API must include your API key in the Authorization header as a Bearer token. Keys are prefixed with vd_sk_.

Authorization: Bearer vd_sk_YOUR_API_KEY

See the Authentication page for full details on obtaining a key, handling auth errors, and security best practices.

Rate Limiting

Rate limits are enforced per API key on a fixed one-minute window.

Plan	Limit
Free	30 requests / minute
Pro	120 requests / minute

Every API response includes headers so you can track your usage:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1720000060

X-RateLimit-Reset is a Unix timestamp indicating when the current window expires and the counter resets. If you exceed the limit, the API returns HTTP 429 Too Many Requests:

{
  "detail": "Rate limit exceeded. Retry after 34 seconds."
}

The response also includes a Retry-After header with the number of seconds to wait before retrying.

Rate limit responses do not consume credits. Credits are only deducted for completed Skill or Workflow Runs.

HTTP Status Codes

The API uses standard HTTP status codes to communicate the outcome of every request.

Code	Meaning	When you see it
`200`	OK	The request succeeded. The response body contains the result.
`400`	Bad Request	The request body is malformed, missing required fields, or invalid.
`401`	Unauthorized	The `key` header is missing or the key format is invalid.
`403`	Forbidden	The key is valid but lacks permission for the requested resource.
`404`	Not Found	The requested resource does not exist in your Workspace.
`429`	Too Many Requests	Your Workspace has exceeded its rate limit. Retry after backoff.
`500`	Internal Server Error	An unexpected error occurred on Valendata’s side.

Error Format

When a request fails, the API returns a JSON body with a detail field:

string | object

required

A message describing what went wrong. For most errors this is a plain string. For structured errors (such as a credit limit response) it may be an object with additional fields.

Here is a representative error response:

{
  "detail": "Skill not found"
}

Explore the API

Authentication

Learn how API keys work, where to create them, and how to keep them secure.

Skills API

Trigger, list, and retrieve your reusable automation Skills via API.

Workflows API

Build and trigger multi-step Workflows that chain Skills, HTTP calls, and transforms.

Runs API

Retrieve run history and inspect the result of any Skill or Workflow execution.

​Base URL

​Request & Response Format

​Authentication

​Rate Limiting

​HTTP Status Codes

​Error Format

​Explore the API

Authentication

Skills API

Workflows API

Runs API

Base URL

Request & Response Format

Authentication

Rate Limiting

HTTP Status Codes

Error Format

Explore the API