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

# API

Amoeba Farm exposes developer surfaces through the web app, backend API, and Petri CLI.

For most users, the safest developer entrypoint is the CLI with JSON output. Direct backend routes are useful for integrations, but they should be treated as versioned product surfaces, not private implementation details.

## Public Developer Paths

| Path        | Use it for                                                                               |
| ----------- | ---------------------------------------------------------------------------------------- |
| Web client  | Normal user market and trading experience.                                               |
| Petri CLI   | Repeatable commands, JSON output, market inspection, wallet checks, and agent workflows. |
| Backend API | Market snapshots, trade preparation, ledger reads, oracle and settlement data.           |

## Public Route Families

The public happy path should focus on:

* market lists and market snapshots;
* charts and oracle status reads;
* trade prepare and submit flows;
* wallet ledger and history reads;
* settlement reads and claim status.

Operator routes, pool provisioning, schedulers, settlement submission, and mutation-heavy custody actions belong in operator or developer reference material, not the first public path.

## CLI JSON

Examples:

```bash
petri --json markets
petri --json markets show ramx
petri --json contracts --market ramx
petri --json oracle recipe ramx
```

Use JSON mode for scripts and agent wrappers.

## API Boundaries

Public developer docs should not expose:

* private keys;
* local keypair paths;
* secret API keys;
* operator-only routes;
* unpublished endpoint internals;
* local-only service assumptions.

## Response Shapes

Next API proxy routes should use:

```json
{ "ok": true, "data": {} }
```

or:

```json
{ "ok": false, "error": { "code": "example", "message": "Human readable message." } }
```

Backend routes may return successful payloads as:

```json
{ "ok": true, "market": "ramx" }
```

and errors as:

```json
{ "ok": false, "message": "Human readable message." }
```

Integrations should check the exact route contract before treating one envelope as universal.

For detailed command coverage, read [Command Reference](https://github.com/SPACE999978/amoeba-oracle-gitbook/tree/main/docs/cli/06-command-reference.md).


---

# 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.amoeba.farm/developer/01-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.