Declaration Spec — paso Docs

This is the full technical specification for usepaso.yaml files.

Root Level

`name`

Type: string
Required: yes
Description: Unique identifier for the API. Used in logs, tool names, and MCP registration.
Example: github-api, stripe-api, slack-api

name: my-api

`version`

Type: string
Required: yes
Description: API version. Follow semantic versioning.
Example: 1.0.0, 2.5.1

version: "1.0.0"

`base_url`

Type: string
Required: yes
Description: Root URL of the API. All capability paths are appended to this.
Example: https://api.github.com, https://api.stripe.com/v1

base_url: https://api.example.com

`auth`

Type: object
Required: no
Description: Authentication configuration. Omit if no auth is needed.

See Auth Configuration below.

`capabilities`

Type: array of objects
Required: yes (can be empty, but must exist)
Description: List of API capabilities to expose as MCP tools.

See Capability Object below.

`forbidden`

Type: object
Required: no
Description: Paths and methods to hide from exposure.

See Forbidden Configuration below.

Auth Configuration

The auth object configures how paso authenticates with your API.

`auth.type`

Type: string (enum)
Required: yes (if auth is defined)
Options: bearer, api_key, basic, oauth2
Description: Authentication method.

`auth.env_var`

Type: string
Required: yes (if auth is defined)
Description: Environment variable name holding the credential.

auth:
  type: bearer
  env_var: GITHUB_TOKEN

The CLI will read $GITHUB_TOKEN at runtime.

Bearer Token Example

auth:
  type: bearer
  env_var: API_TOKEN

Adds header: Authorization: Bearer <value-of-env-var>

API Key Example

auth:
  type: api_key
  env_var: API_KEY
  header: X-API-Key

Adds header: X-API-Key: <value-of-env-var>

Optional header field specifies the header name. Defaults to Authorization.

Basic Auth Example

auth:
  type: basic
  env_var: API_CREDENTIALS

Expects env_var in format: username:password

Adds header: Authorization: Basic <base64-encoded-credentials>

OAuth2 Example

auth:
  type: oauth2
  env_var: OAUTH_TOKEN

Adds header: Authorization: Bearer <value-of-env-var>

Capability Object

Each capability in the capabilities array represents one API operation exposed as a tool.

`name`

Type: string
Required: yes
Description: Unique tool name. Must be unique within the declaration.
Example: list_repos, create_issue, delete_user

- name: list_repos

`description`

Type: string
Required: yes
Description: What the tool does. Claude uses this to decide when to call it.
Example: List all repositories for the authenticated user

  description: List all repositories for the authenticated user

`method`

Type: string (enum)
Required: yes
Options: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
Description: HTTP method.

  method: GET

`path`

Type: string
Required: yes
Description: Endpoint path relative to base_url. Use {param} for path variables.
Example: /repos/{owner}/{repo}, /users/{id}, /events

  path: /repos/{owner}/{repo}/issues

`permission`

Type: string (enum)
Required: yes
Options: read, write, admin
Description: Permission tier. See Permissions & Safety.

  permission: write

`consent_required`

Type: boolean
Required: no
Default: false
Description: If true, Claude must ask for user approval before executing.

  consent_required: true

`inputs`

Type: array of objects
Required: no
Description: Input parameters for the capability.

See Input Object below.

`constraints`

Type: object
Required: no
Description: Rate limiting and resource constraints.

See Constraint Object below.

Input Object

Each object in the inputs array represents a parameter.

`name`

Type: string
Required: yes
Description: Parameter name. Must match path variables or API query/body parameter names.

- name: owner

`type`

Type: string (enum)
Required: yes
Options: string, number, boolean, object, array
Description: Data type of the parameter.

  type: string

`description`

Type: string
Required: no
Description: What the parameter does.

  description: Repository owner username

`required`

Type: boolean
Required: no
Default: false
Description: If true, Claude must provide this parameter.

  required: true

`default`

Type: any
Required: no
Description: Default value if not provided.

  default: 30

`enum`

Type: array
Required: no
Description: List of allowed values.

  enum:
    - open
    - closed
    - all

`constraints`

Type: object
Required: no
Description: Input-specific constraints.

  constraints:
    max_value: 1000
    required_with: email

Constraint Object

Constraints limit API usage and prevent abuse.

`rate_limit`

Type: number
Description: Maximum calls per minute.

constraints:
  rate_limit: 10

`max_items`

Type: number
Description: Maximum number of items returned.

constraints:
  max_items: 100

`max_value`

Type: number
Description: Maximum numeric value for an input.

constraints:
  max_value: 1000

`required_with`

Type: string
Description: This parameter is only allowed if another parameter is present.

- name: password
  constraints:
    required_with: email

Forbidden Configuration

Hide paths and methods globally.

`forbidden.paths`

Type: array of strings
Description: Paths to hide. Supports glob patterns (* wildcard).

forbidden:
  paths:
    - /admin/*
    - /internal/*
    - /settings/billing

`forbidden.methods`

Type: array of strings
Options: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
Description: Methods to hide.

forbidden:
  methods:
    - DELETE

Complete Schema Example

# Root configuration
name: github-api
version: "1.0.0"
base_url: https://api.github.com

# Authentication
auth:
  type: bearer
  env_var: GITHUB_TOKEN

# Capabilities
capabilities:
  # Read capability
  - name: list_repos
    description: List repositories for the authenticated user
    method: GET
    path: /user/repos
    permission: read
    inputs:
      - name: type
        type: string
        description: Filter by repository type
        default: all
        enum:
          - all
          - owner
          - public
      - name: per_page
        type: number
        description: Number of repositories per page
        default: 30
    constraints:
      rate_limit: 10
      max_items: 100

  # Write capability with consent
  - name: create_repo
    description: Create a new repository
    method: POST
    path: /user/repos
    permission: write
    consent_required: true
    inputs:
      - name: name
        type: string
        required: true
        description: Repository name
      - name: description
        type: string
        description: Repository description
      - name: private
        type: boolean
        default: false
        description: Make the repository private

  # Capability with path variables
  - name: create_issue
    description: Create an issue in a repository
    method: POST
    path: /repos/{owner}/{repo}/issues
    permission: write
    inputs:
      - name: owner
        type: string
        required: true
        description: Repository owner
      - name: repo
        type: string
        required: true
        description: Repository name
      - name: title
        type: string
        required: true
        description: Issue title
      - name: body
        type: string
        description: Issue description

  # Admin capability
  - name: delete_repo
    description: Delete a repository
    method: DELETE
    path: /repos/{owner}/{repo}
    permission: admin
    consent_required: true
    inputs:
      - name: owner
        type: string
        required: true
      - name: repo
        type: string
        required: true

# Hide sensitive endpoints
forbidden:
  paths:
    - /admin/*
    - /app/installations/*/suspended
  methods:
    - DELETE

Type System

string

Text value. Used for names, descriptions, IDs.

- name: username
  type: string

number

Integer or floating-point value.

- name: limit
  type: number

boolean

True or false.

- name: private
  type: boolean

object

JSON object. Use for complex nested data.

- name: metadata
  type: object

Claude will pass a JSON object: {"key": "value", ...}

array

JSON array. Use for lists.

- name: tags
  type: array

Claude will pass a JSON array: ["item1", "item2", ...]

Validation Rules

paso validates:

All required fields are present
Field types are correct
name values are unique within capabilities
Auth type is valid
Path variables in path are covered by inputs
Permission values are valid
Input types are valid
No invalid field names

Run validation:

usepaso validate

Next steps

Declarations — learn by example
CLI Commands — reference all commands
Permissions & Safety — understand safety features