GET /api/skills/{skill_id} — Get a Single Skill's Details

GET /api/skills/{skill_id} returns the full definition of a single Skill, including its parameter schema and output schema. Use this endpoint to understand exactly which parameters a Skill expects before calling POST /v1/skills/run, or to render a dynamic form in your own application that drives Skill execution.

Endpoint

GET https://api.valendata.com/api/skills/{skill_id}

Authentication

This endpoint requires a session token, not an API key. Pass your JWT in the Authorization header:

Authorization: Bearer YOUR_SESSION_TOKEN

To get a session token, call POST /api/auth/login with your email and password. The response includes a token field, use that here.

Path Parameters

string

required

The unique identifier of the Skill to retrieve. Skill IDs follow the format skl_.... Retrieve a full list of your Skill IDs from GET /api/skills.

Example Request

cURL
Python
Node.js

curl https://api.valendata.com/api/skills/skl_b281b8165a23 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

import requests

skill_id = "skl_b281b8165a23"
response = requests.get(
    f"https://api.valendata.com/api/skills/{skill_id}",
    headers={"Authorization": "Bearer YOUR_SESSION_TOKEN"},
)

skill = response.json()
print(skill["name"], "—", skill["description"])
print("Parameters:", skill["parameters"])

const skillId = "skl_b281b8165a23";

const response = await fetch(
  `https://api.valendata.com/api/skills/${skillId}`,
  {
    headers: { "Authorization": "Bearer YOUR_SESSION_TOKEN" },
  }
);

const skill = await response.json();
console.log(skill.name);
console.log("Output schema:", skill.output_schema);

Response

A successful request returns HTTP 200 with a single Skill object containing the following fields.

Core Fields

string

The Skill’s unique identifier (skl_...).

string

Human-readable name of the Skill.

string

A plain-English description of what the Skill does, as configured when the Skill was created.

string

The currently active published version of the Skill. Valendata uses semantic versioning. When you publish an updated Skill, the version increments and prior API calls remain unaffected.

string

ISO 8601 UTC timestamp of when the Skill was first created.

Parameter Schema

array

An array of parameter definition objects that describe every input the Skill accepts. Each object contains the following fields:

Show Parameter definition fields

string

The key name used in the parameters map when calling POST /v1/skills/run.

string

The expected data type for this parameter. One of "string", "number", "boolean", or "array".

boolean

When true, the parameter must be supplied in every run request. Omitting a required parameter causes the run to return a 400 error.

string

A human-readable explanation of what the parameter controls and how to format its value.

Output Schema

object

A JSON Schema object that defines the structure of the data array returned by every run of this Skill. Valendata enforces this schema on each run: if the agent cannot produce output that matches the schema, the run fails cleanly rather than returning malformed data.Use this schema to validate run output in your own code or to auto-generate TypeScript types for the Skill’s response.

Example Response

{
  "id": "skl_b281b8165a23",
  "name": "Google Maps SF Software Companies Scraper",
  "description": "Scrapes software companies in San Francisco from Google Maps, including name, website, address, rating, and reviews.",
  "version": "1.0.0",
  "created_at": "2026-08-01T14:22:11Z",
  "parameters": [
    {
      "name": "location",
      "type": "string",
      "required": false,
      "description": "The city or region to search within. Defaults to 'San Francisco, CA' if omitted."
    },
    {
      "name": "max_results",
      "type": "number",
      "required": false,
      "description": "Maximum number of companies to return. Defaults to 20, maximum 100."
    }
  ],
  "output_schema": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name":    { "type": "string" },
        "website": { "type": "string" },
        "address": { "type": "string" },
        "rating":  { "type": "number" },
        "reviews": { "type": "integer" }
      },
      "required": ["name", "address"]
    }
  }
}

Error Handling

HTTP Status	Meaning
`401`	Unauthorized, session token is missing or expired.
`404`	Skill not found, the provided `skill_id` does not exist in this Workspace.
`429`	Rate limited, reduce your request frequency.
`500`	Internal error, check status.valendata.com.

A Skill must be published to appear via the API. Skills that are saved as drafts in the dashboard are not returned by this endpoint or by GET /api/skills.

Overview

Skills

Workflows

Runs

GET /api/skills/{skill_id} — Get a Single Skill's Details

Endpoint

Authentication

Path Parameters

Example Request

Response

Core Fields

Parameter Schema

Output Schema

Example Response

Error Handling

​Endpoint

​Authentication

​Path Parameters

​Example Request

​Response

​Core Fields

​Parameter Schema

​Output Schema

​Example Response

​Error Handling

Endpoint

Authentication

Path Parameters

Example Request

Response

Core Fields

Parameter Schema

Output Schema

Example Response

Error Handling