Agent Integration Guide

This guide helps AI agents, automated tools, and developers integrate with the Release API programmatically. Choose the integration path that fits your workflow.

Quick Start: First Authenticated API Call

1. Install the Release CLI and run release auth login.

2. Read your credentials from ~/.release.yaml:

login: [email protected]
token: your-token-here

1. Make your first request:

curl -s https://api.release.com/api/v1/accounts \
  -H "X-User-Email: [email protected]" \
  -H "X-User-Token: your-token-here" \
  -H "Accept: application/json"

Integration Paths

Path 1: OpenAPI-Based Integration (Recommended)

The canonical machine-readable API contract is published at:

https://api.release.com/openapi.json

Use this to:

• Generate typed API clients in any language (e.g. openapi-generator, oapi-codegen)

• Feed LLM tool-use frameworks (function calling, tool schemas)

• Build MCP servers that expose Release operations as tools

• Validate request/response shapes automatically

Example — generate a Python client:

openapi-generator-cli generate \
  -i https://api.release.com/openapi.json \
  -g python \
  -o ./release-client

Example — use with an LLM tool framework:

import httpx

spec = httpx.get("https://api.release.com/openapi.json").json()
# Parse spec["paths"] to extract operations for tool definitions

Path 2: MCP-Based Docs Retrieval

Release documentation is available via standard discovery files that MCP servers and agents can consume:

Resource	URL	Content
llms.txt	https://docs.release.com/llms.txt	Structured index of all documentation pages
llms-full.txt	https://docs.release.com/llms-full.txt	Full documentation content in a single file
Sitemap	https://docs.release.com/sitemap-pages.xml	XML sitemap for crawlers

These files follow the llmstxt.org convention and are auto-generated by GitBook.

Use this path when:

• Your agent needs to understand Release concepts, not just call endpoints

• You're building a RAG pipeline over Release documentation

• You want to answer "how do I..." questions about the platform

Example — fetch docs index for context:

curl -s https://docs.release.com/llms.txt

Path 3: Manual REST / curl Workflow

For scripting, CI/CD pipelines, or quick one-off automation without generated clients:

1. Authenticate with headers (see Quick Start above)

2. Use the API reference pages for endpoint details

3. Follow these conventions:

Convention	Detail
Content-Type	application/json for all requests
IDs	Hashid strings (e.g. "abc123")
Timestamps	ISO 8601 (e.g. 2025-01-15T10:30:00Z)
Pagination	?page=1&per_page=25 on list endpoints
Errors	{"error": "message"} or {"errors": [...]}

Example — list environments for an app:

curl -s "https://api.release.com/api/v1/apps/APP_ID/environments?per_page=10" \
  -H "X-User-Email: [email protected]" \
  -H "X-User-Token: your-token-here" \
  -H "Accept: application/json" | jq '.[] | {id, name, state}'

Host Differences

Release uses two API hosts. Ensure your integration targets the correct one:

API	Base URL	Auth Headers
Platform API	https://api.release.com	X-User-Email + X-User-Token
AI Sandbox API	https://backend-{handle}-envs.gcp.release.com	X-User-Email + X-User-Token

The AI Sandbox base URL is scoped to your environment handle. Example: https://backend-thor-envs.gcp.release.com.

Troubleshooting

Symptom	Cause	Fix
401 Unauthorized	Missing or invalid auth headers	Re-run release auth login and check ~/.release.yaml
404 Not Found on sandbox endpoints	Wrong base URL / handle	Verify the environment handle in the URL matches your target
403 Forbidden	Account-level endpoint with user-level auth	Use X-Account-ID + X-Account-Token for account-scoped operations
Empty response on list endpoints	No results on current page	Check pagination — try ?page=1&per_page=100
openapi.json returns error	Endpoint unreachable or server issue	Verify URL is https://api.release.com/openapi.json and retry

Related Resources

• Authentication reference — full header details for all auth modes

• Platform API — accounts, apps, environments, deploys, clusters, builds

• AI Sandbox API — sessions, executions, snapshots, events, memory stores

• GraphQL API — mutations and complex queries