Declaration Spec

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

Root Level

A declaration has four top-level fields:

Field	Type	Required	Description
version	string	Yes	Must be "1.0"
service	object	Yes	Service metadata
capabilities	array	Yes	List of agent-accessible actions
permissions	object	No	Permission tier assignments

version: "1.0"

service:
  name: Sentry
  description: Error monitoring for software teams
  base_url: https://sentry.io/api/0
  auth:
    type: bearer

capabilities:
  - name: list_issues
    # ...

permissions:
  read:
    - list_issues

---

Service Object

Field	Type	Required	Description
name	string	Yes	Human-readable service name
description	string	Yes	What the service does (used by agents for discovery)
base_url	string	Yes	Base URL of the API (e.g., https://api.sentry.io)
version	string	No	API version
auth	object	No	Authentication configuration

service:
  name: Stripe
  description: Payment processing and billing infrastructure
  base_url: https://api.stripe.com/v1
  version: "v1"
  auth:
    type: bearer

---

Auth Object

Field	Type	Required	Description
type	string	Yes	One of: api_key, bearer, oauth2, none
header	string	No	Header name for api_key/bearer (default: Authorization)
prefix	string	No	Token prefix (e.g., Bearer, Token)

The auth token is always provided at runtime via the USEPASO_AUTH_TOKEN environment variable.

Bearer

auth:
  type: bearer

Sends: Authorization: Bearer <USEPASO_AUTH_TOKEN>

API Key with Custom Header

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

Sends: X-API-Key: <USEPASO_AUTH_TOKEN>

API Key with Custom Prefix

auth:
  type: api_key
  prefix: Token

Sends: Authorization: Token <USEPASO_AUTH_TOKEN>

No Auth

auth:
  type: none

No authentication header is sent. If USEPASO_AUTH_TOKEN is set, it is ignored.

---

Capability Object

Each item in capabilities represents one action an agent can take.

Field	Type	Required	Description
name	string	Yes	Machine-readable identifier (snake_case, ^[a-z][a-z0-9_]*$)
description	string	Yes	What this action does
method	string	Yes	GET, POST, PUT, PATCH, DELETE
path	string	Yes	API path starting with /, may include {parameters}
permission	string	Yes	read, write, or admin
consent_required	boolean	No	Agent must confirm with user before executing. Default: false
inputs	object	No	Parameters the agent sends
output	object	No	What the API returns
constraints	array	No	Business rules and limits

- name: list_issues
  description: List issues in a project, filtered by status
  method: GET
  path: /projects/{organization_slug}/{project_slug}/issues/
  permission: read
  inputs:
    organization_slug:
      type: string
      required: true
      description: The organization slug
      in: path
  output:
    issues:
      type: array
      description: List of issue objects

---

Inputs Object

Keys are parameter names. Values describe the parameter.

Field	Type	Required	Description
type	string	Yes	string, integer, number, boolean, enum, array, object
required	boolean	No	Default: false
description	string	Yes	What this parameter does
values	array	For enum	Allowed values (required when type is enum)
default	any	No	Default value
in	string	No	query, path, body, header. Default: body for POST/PUT/PATCH, query for GET/DELETE

String Parameter

inputs:
  query:
    type: string
    description: "Search query (e.g., 'is:unresolved')"
    in: query

Path Parameter

inputs:
  issue_id:
    type: string
    required: true
    description: The issue ID
    in: path

Path parameters referenced in path (e.g., {issue_id}) must exist in inputs with in: path.

Enum Parameter

inputs:
  status:
    type: enum
    required: true
    values: [resolved, unresolved, ignored]
    description: New status for the issue

Parameter with Default

inputs:
  limit:
    type: integer
    description: Number of results (1-100)
    default: 10
    in: query

Boolean Parameter

inputs:
  include_archived:
    type: boolean
    description: Include archived items in results
    default: false
    in: query

---

Output Object

Keys are field names. Values describe the response field.

Field	Type	Required	Description
type	string	Yes	string, integer, number, boolean, object, array
description	string	No	What this field contains

output:
  id:
    type: string
  email:
    type: string
  name:
    type: string
  balance:
    type: integer
    description: Current balance in cents

---

Constraints Array

Each constraint is an object with one or more rules.

Field	Type	Description
max_per_hour	integer	Rate limit per hour
max_per_request	integer	Max items per request (bulk operations)
max_value	number	Max numeric value
allowed_values	array	Restrict an input to specific values
requires_field	string	Another input that must be present
description	string	Human-readable rule explanation

constraints:
  - max_per_hour: 500
    description: Payment creation is rate-limited
  - max_value: 99999999
    description: Maximum single charge is $999,999.99
  - requires_field: currency
    description: Currency is required when specifying an amount

---

Permissions Object

Groups capabilities into permission tiers.

Field	Type	Description
read	array of strings	Capability names agents can call with read-only access
write	array of strings	Capability names requiring write access
admin	array of strings	Capability names requiring admin access
forbidden	array of strings	Capability names agents may never call

permissions:
  read:
    - list_customers
    - get_customer
    - list_invoices
  write:
    - create_customer
    - create_payment_intent
  admin:
    - refund_payment
  forbidden:
    - delete_customer

If permissions is omitted, each capability’s permission field is used directly.

Validation Rules for Permissions

• Every capability name in read, write, or admin must exist in capabilities
• The forbidden tier may reference capability names not declared (to explicitly block endpoints)
• A capability cannot appear in both a permission tier and forbidden

---

Validation Rules

1. version must be "1.0"
2. service.name must be non-empty
3. service.description must be non-empty
4. service.base_url must be a valid URL
5. Each capability name must be unique
6. Each capability name must be snake_case (^[a-z][a-z0-9_]*$)
7. method must be GET, POST, PUT, PATCH, or DELETE
8. path must start with /
9. Parameters in path (e.g., {project_id}) must exist in inputs with in: path
10. enum type inputs must have values defined
11. Permission tier references must match declared capability names
12. A capability cannot appear in both a tier and forbidden

Run usepaso validate to check all rules. Use usepaso validate --strict for best-practice warnings.

---

JSON Schema

For editor autocomplete, point your YAML language server at the JSON Schema:

# yaml-language-server: $schema=https://raw.githubusercontent.com/5h1vmani/usepaso/main/spec/usepaso.schema.json
version: "1.0"

The schema is the machine-readable source of truth: spec/usepaso.schema.json

The human-readable spec: spec/usepaso-spec.md