> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/reference-documentation/release-api/agent-integration-guide.md).

# 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](/cli/installation.md) and run `release auth login`.
2. Read your credentials from `~/.release.yaml`:

```yaml
login: you@example.com
token: your-token-here
```

3. Make your first request:

```bash
curl -s https://api.release.com/api/v1/accounts \
  -H "X-User-Email: you@example.com" \
  -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:**

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

**Example — use with an LLM tool framework:**

```python
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](https://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:**

```bash
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](/reference-documentation/release-api.md) 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:**

```bash
curl -s "https://api.release.com/api/v1/apps/APP_ID/environments?per_page=10" \
  -H "X-User-Email: you@example.com" \
  -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](/reference-documentation/release-api/authentication.md) — full header details for all auth modes
* [Platform API](/reference-documentation/release-api/platform-api.md) — accounts, apps, environments, deploys, clusters, builds
* [AI Sandbox API](/reference-documentation/release-api/ai-sandbox-api.md) — sessions, executions, snapshots, events, memory stores
* [GraphQL API](/reference-documentation/release-api/graphql-api.md) — mutations and complex queries


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.release.com/reference-documentation/release-api/agent-integration-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.