API Profiles

API Profiles

API profiles are YAML files that describe a remote API: base URL, environment variables, authentication, and a tree of commands.

Top-level fields

Field	Description
name	Profile name (used for install and load)
version	Profile version string
description	Human-readable summary
base_url	Default API root URL
env	Declared environment variables (${VAR} in templates)
auth	Optional default authentication
errors	Optional API-root response templates
commands	Command tree

Commands

Commands can be nested. The core resolves paths with dot notation, for example repos.issues.create.

Hybrid commands support both an endpoint on the same node and child subcommands (for example repos as GET /repos and as parent of issues).

Endpoint and params

Endpoints use {param} placeholders. Path placeholders work without a params: entry (implicit required path params).

get-repo:
  endpoint: /repos/{owner}/{repo}
  method: GET
  params:
    owner:
      type: string
      required: true
    repo:
      type: string
      required: true

Environment variables

Templates use ${VAR}. Declared env names must be unique alphanumeric or underscore identifiers.

EnvMode::Auto reads from the OS environment. Manual requires explicit values via the client builder.

Authentication

Supported types:

• Bearer token
• API key (header, query, or cookie)
• HTTP basic or custom header auth

Cookie auth rejects injection characters (;, CRLF).

Body

Exactly one body type per command: JSON, form, multipart, or raw.

Runtime body in call() overrides the YAML body definition.

Responses

Templated messages use {input.*} and {output.*}. Missing fields keep the placeholder (for example {output.missing}) instead of becoming empty strings.

Fallback order includes command-level responses, API-root errors, and {status} in templates.

Reference example

See examples/github_api.yaml in the repository.