> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valendata.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Fetch complete details for one Skill by ID, including its full parameter schema and the JSON Schema that governs its output structure.

`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`](/api-reference/skills/run), or to render a dynamic form in your own application that drives Skill execution.

## Endpoint

```text theme={null}
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:

```http theme={null}
Authorization: Bearer YOUR_SESSION_TOKEN
```

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

## Path Parameters

<ParamField path="skill_id" type="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`](/api-reference/skills/list).
</ParamField>

## Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.valendata.com/api/skills/skl_b281b8165a23 \
      -H "Authorization: Bearer YOUR_SESSION_TOKEN"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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"])
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>
</Tabs>

## Response

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

### Core Fields

<ResponseField name="id" type="string">
  The Skill's unique identifier (`skl_...`).
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable name of the Skill.
</ResponseField>

<ResponseField name="description" type="string">
  A plain-English description of what the Skill does, as configured when the Skill was created.
</ResponseField>

<ResponseField name="version" type="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.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 UTC timestamp of when the Skill was first created.
</ResponseField>

### Parameter Schema

<ResponseField name="parameters" type="array">
  An array of parameter definition objects that describe every input the Skill accepts. Each object contains the following fields:

  <Expandable title="Parameter definition fields">
    <ResponseField name="name" type="string">
      The key name used in the `parameters` map when calling [`POST /v1/skills/run`](/api-reference/skills/run).
    </ResponseField>

    <ResponseField name="type" type="string">
      The expected data type for this parameter. One of `"string"`, `"number"`, `"boolean"`, or `"array"`.
    </ResponseField>

    <ResponseField name="required" type="boolean">
      When `true`, the parameter must be supplied in every run request. Omitting a required parameter causes the run to return a `400` error.
    </ResponseField>

    <ResponseField name="description" type="string">
      A human-readable explanation of what the parameter controls and how to format its value.
    </ResponseField>
  </Expandable>
</ResponseField>

### Output Schema

<ResponseField name="output_schema" type="object">
  A [JSON Schema](https://json-schema.org/) 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.
</ResponseField>

### Example Response

```json theme={null}
{
  "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](https://status.valendata.com). |

<Info>
  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`.
</Info>