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

# observal api

Call an authenticated JSON endpoint when no dedicated high-level command exists.

## Examples

```bash
observal api GET /api/v1/teams --output json
observal api GET /api/v1/agents --param limit=10 --param page=2 --output json
observal api POST /api/v1/teams --from-file team.json --output json
cat team.json | observal api POST /api/v1/teams --output json
```

Methods are `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. Paths must be canonical relative `/api/v1/` paths. Full URLs, traversal segments, fragments, and inline query strings are rejected. Use repeatable `--param KEY=VALUE` options for query parameters.

The command uses the configured bearer token. It does not accept arbitrary authorization headers, so it cannot forward credentials to another host.

## Request bodies

`POST`, `PUT`, `PATCH`, and `DELETE` accept one JSON object from `--from-file` or standard input. A file takes precedence when both are present. `GET` rejects request bodies.

## Output

Table mode renders arbitrary objects as field and value rows. JSON mode preserves the endpoint response exactly, including top-level arrays. This raw behavior is intentional and is the exception to dedicated list commands, which use the standard list envelope.

## Errors and retries

The command uses the shared categorized error contract and preserves server request IDs. Automatic transient retries apply only to `GET`. After an uncertain mutation failure, read endpoint state before retrying. See [Mutation retries and idempotency](/cli-reference/idempotency.md).

Prefer dedicated commands when they exist because they provide stronger validation, safer confirmation, and domain-specific output.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/cli-reference/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.