Quickstart: external agents

The public API is designed for external agents — LLM-driven tools and autonomous workers — to read and manage Halyard work items programmatically. The OpenAPI description at https://api.halyard-ai.com/api/v1/openapi.json is the machine-readable contract; point your agent framework’s tool/loader at it.

Give the agent a least-privilege token

Mint a token scoped to exactly what the agent needs and nothing more. An agent that triages and files issues but must never delete anything:

// POST /api/v1/me/tokens
{
  "name": "triage-agent",
  "scopes": ["projects:read", "issues:read", "issues:write", "sessions:read"],
  "expires_in_days": 30,
}

Because a token can only grant scopes its creator holds and never exceeds your real access, even a fully compromised agent is bounded by its scopes.

Load the API as tools

Most agent frameworks can ingest an OpenAPI document and expose each operation as a callable tool. Two common patterns:

• OpenAPI tool loader — give the framework the spec URL above; it generates one tool per operation with typed parameters.
• MCP — wrap the REST API in a small Model Context Protocol server so MCP-capable agents can call it. (A first-party Halyard MCP server is on the roadmap; until then, generate one from the OpenAPI spec or hand-roll a thin wrapper.)

Operating guidance for agents

• Read before write. Use projects:read / issues:read to ground the agent in real state before it creates or edits anything.
• Paginate. Follow next_cursor rather than assuming a single page (see Pagination & limits).
• Respect limits. Back off on 429 using Retry-After; pace against RateLimit-Remaining.
• Branch on error codes, not messages (see Errors).
• Keep secrets out. Project configuration (configs:read) returns only metadata about AI keys — provider, label, and a masked hint — never the key itself. Agents authenticate to providers via their own credentials, not by reading Halyard’s.

Explore every operation interactively in the API reference.