# GizStack APIs

The same operations serve people, scripts and agents.

| API | Address |
| --- | --- |
| Run Gizlang | `POST /play/run` |
| Export a project | `POST /play/export` |
| Published releases | `GET /api/releases` |
| Console actions as MCP tools | `/mcp` ([agents](/docs/platform/agents#mcp)) |
| A team Agent as the Responses API | `POST https://agent.giz.sh/v1/responses` ([agents](/docs/platform/agents#responses-api)) |
| A team Agent to other agents (A2A) | `/a2a/AGENT` ([agents](/docs/platform/agents#agent-to-agent)) |
| Start an Agent from a webhook | `POST /hooks/TRIGGER/KEY` ([agents](/docs/platform/agents#triggers)) |
| Every page as Markdown | [/llms.txt](/llms.txt) |

## Run Gizlang

Send `POST /play/run` with `Content-Type: application/json` and a UTF-8 object:

```json
{
  "source": "function main(): void { print(\"Hello from Gizlang.\"); }"
}
```

### Requests and limits

- The operation also accepts ordinary form fields.
- Browser requests must satisfy the same-origin policy. Cross-site requests are refused.
- Source, output, runtime, memory and admission limits apply equally to people and agents.
- The worker compiles an ordinary pinned Gizlang package with its declared capability grants.
- It does not grant arbitrary native declarations, files, network or processes to the submitted program.

### Result

JSON execution and validation results use `gizlang.playground-result.v1`:

| Field | Meaning |
| --- | --- |
| `schema` | The identifier of the result contract. |
| `toolchain` | The exact identity of the configured deployed compiler and release. |
| `status` | A stable outcome identifier. |
| `phase` | The input, admission, preparation, compilation or execution phase. |
| `exitCode` | The exit code of the child when available. Otherwise `-1`. |
| `stdout`, `stderr` | Bounded worker output and diagnostics. |
| `elapsedMilliseconds` | The reported work duration. |
| `limits` | The applied worker resource policy. |

- Check `status=completed` and the reported toolchain. An HTTP response alone does not prove successful execution.

| Status | Meaning |
| --- | --- |
| `completed` | Compilation and program execution succeeded. |
| `compile_error` | The compiler rejected the submitted program. |
| `runtime_error` | The compiled program exited unsuccessfully. |
| `output_limit` | Compiler or program output went past its bound. |
| `timeout` | A worker went past its deadline. |
| `unavailable` | Necessary worker configuration, resources or execution failed. |
| `busy` | Worker and queue capacity are full. |
| `origin_refused` | The request failed the same-origin policy. |
| `request_limit` | The encoded request went past its limit. |
| `invalid_request` | The input was not an accepted JSON object or form. |
| `invalid_source` | The source failed input admission. |
| `invalid_download` | The requested export filename is not supported. |

### HTTP status

| Condition | HTTP status |
| --- | --- |
| A busy queue | 429 |
| An unavailable worker | 503 |
| A worker deadline | 504 |
| A validation failure | The corresponding 4xx status |
| A compile or runtime failure | Can be 200. These are execution results. |

Responses keep the submitted source for the browser form, and escape worker output.

## Export an ordinary project

Send `POST /play/export` with the same `source` and `license` fields.

| Request | Response |
| --- | --- |
| `file=main.giz` or `file=package.json` | A download of that individual project file |
| No `file` field | JSON that contains both ordinary files, the local command and the toolchain provenance |

Export does not run the submitted program.

- Keep the matching files together. The manifest pins the exact source and import grants.
- When you edit the source, refresh the ordinary package pins.
- Run the export locally with the toolchain version that it reports.

## Published releases

`GET /api/releases` gives the release catalog as JSON: each release with its target, version,
requirements and installer address. It returns 503 when the catalog is unavailable.

## Packages

The [package guide](/docs/guides/packages) gives the registry API and the `giz` commands that use it.