API Specifications

API specs are YAML definitions for extracting data from REST APIs. They handle authentication, pagination, response processing, and incremental sync automatically.

Building specs from Python? Load the sling-python skill — sling.api_spec provides typed builders (ApiSpec, Endpoint, ...) that validate and serialize to this YAML.

Gather first

Resolve each row before you write YAML, in this order: the user's request, existing files, discovery (MCP / CLI), then the default in the table. Ask the user only for rows that stay unresolved, one at a time, with a proposed default. If every row resolves, do not ask — build, and state the assumptions you took. Confirm first only for destructive resolutions (for example a mode that drops or rewrites existing tables).

Never invent endpoint paths. Never paste cookies, tokens, or password fields into the spec. Use agent-browser (snapshot, read, open) for live docs. If the page needs a login or CAPTCHA, ask the user to allow Chrome remote debugging, then use --auto-connect or --cdp 9222.

When to Use

• Extract data from REST APIs (GET endpoints only)
• Build incremental sync workflows
• Handle complex pagination patterns
• Process nested JSON responses
• Chain multiple API calls with queues

Basic Structure

name: "My API"
description: "Data extraction from My API"

authentication:
  type: "static"
  headers:
    Authorization: "Bearer {secrets.api_token}"

defaults:
  state:
    base_url: "https://api.example.com/v1"
  request:
    headers:
      Accept: "application/json"

endpoints:
  users:
    description: "Fetch users"
    request:
      url: "{state.base_url}/users"
    response:
      records:
        jmespath: "data[]"
        primary_key: ["id"]

Live API docs

sling assist setup installs the agent-browser MCP server (Vercel Labs). Use it to read JS-rendered docs:

• open / snapshot / read for page text
• --auto-connect or --cdp 9222 when the page needs a login or CAPTCHA
• Do not paste cookies, tokens, or password fields into the spec

If agent-browser is missing, run sling assist setup. Then run agent-browser install once if Chrome is not on the machine.

MCP Operations

Parse a Spec

{
  "action": "validate",
  "input": {"file_path": "/path/to/spec.yaml"}
}

Test Endpoints

{
  "action": "test",
  "input": {
    "connection": "MY_API",
    "endpoints": ["users"],
    "debug": true,
    "limit": 10
  }
}

MCP api_spec test tests the connection's CONFIGURED spec, not your local file. A SUCCESS there does not validate your draft. Before you test, point the connection at your draft. If you did not re-point the spec, you have not tested your work.

sling conns set CONN "spec=file://$PWD/spec.yaml"
sling conns test CONN --endpoints <name> --debug

Pass spec_file_path in the MCP test input to test your draft file directly, without re-pointing the connection:

{
  "action": "test",
  "input": {"connection": "MY_API", "spec_file_path": "/path/to/spec.yaml", "endpoints": ["users"], "debug": true}
}

Reference only {secrets.X} keys that exist on the connection. Learn the key names from the connection's existing spec (its authentication block is ground truth) or from the connection's property keys — names only, never values. An unknown secret renders empty and produces 401s. Do not invent names like api_token when the key is token.

Definition of done for a spec task: the endpoint test against YOUR spec file returns more than 0 records with no 4xx. A zero-record result means records.jmespath is wrong — fix the path (see RESPONSE.md). Do not ship.

Parent-child extraction uses depends_on plus a queue. See QUEUES.md.

Topics Reference

This skill includes detailed documentation for each aspect of API specification building:

Quick Reference

Authentication Types

Pagination Patterns

Variable Scopes

Full Documentation

See https://docs.slingdata.io/concepts/api-specs.md for complete reference.