slingdata-io/sling-cli/sling-api-specs

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.