# API Reference

> **Preview**: Paths, fields, and auth headers may change before GA; refer to the released OpenAPI specification and console for official documentation.

***

## Transport and Security

| Item                 | Agreement (Design)                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------- |
| **TLS**              | TLS 1.3; versions 1.0/1.1/1.2 disabled                                                        |
| **mTLS**             | Admin operations like Vault writes recommended to use **client certificates**                 |
| **Cipher Suites**    | Only `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`                                 |
| **Application Auth** | `Authorization: Bearer <api_key>` or environment-stratified Token scheme (per implementation) |

***

## Base URL (Placeholder)

| Environment | Base URL (Example)                               |
| ----------- | ------------------------------------------------ |
| Sandbox     | `https://sandbox.control.toani.ai` (placeholder) |
| Production  | `https://control.toani.ai` (placeholder)         |

***

## Credential Plane: Vault Management (Excerpt)

Example design patterns (path prefix per implementation, e.g., `/v1/vault/...`):

### Create Credential

```http
POST /v1/vault/credentials
Content-Type: application/json
Authorization: Bearer <admin_or_service_token>

{
  "namespace": "prod-schwab-service",
  "label": "schwab-api-key-2026",
  "type": "api_key",
  "sensitivity": 1,
  "value": "sk_live_...",
  "rotation_policy": { "type": "scheduled", "interval_days": 90 },
  "tags": { "service": "schwab", "env": "prod" }
}
```

**Response (no plaintext field)**:

```json
{
  "credential_id": "cred_8821abc",
  "namespace": "prod-schwab-service",
  "label": "schwab-api-key-2026",
  "sensitivity": 1,
  "created_at": "2026-03-11T...",
  "fingerprint": "sha256:ab12..."
}
```

### Other Management Operations (Planned)

| Method  | Path (Indicative)           | Description                                                         |
| ------- | --------------------------- | ------------------------------------------------------------------- |
| `GET`   | `/v1/vault/credentials`     | List metadata                                                       |
| `GET`   | `/v1/vault/credentials/:id` | Metadata, no plaintext                                              |
| `PATCH` | `/v1/vault/policies/...`    | Policy binding (may be under Policy service if Vault is a boundary) |

***

## Policy Plane: Policies (Planned)

| Method | Path (Indicative)                  | Description                      |
| ------ | ---------------------------------- | -------------------------------- |
| `POST` | `/v1/policies`                     | Create new policy version        |
| `GET`  | `/v1/policies/:policy_id`          | Get current or specified version |
| `GET`  | `/v1/policies/:policy_id/versions` | Version history and signatures   |

**Request body** logical model: see [toani Control System Architecture](/toani-control/security-architecture.md) for policy field details.

***

## Execution: Execution (Planned)

| Method | Path (Indicative)              | Description                        |
| ------ | ------------------------------ | ---------------------------------- |
| `POST` | `/v1/executions`               | Create execution (sync or async)   |
| `GET`  | `/v1/executions/:execution_id` | Query status / result              |
| `POST` | `/v1/batch-authorizations`     | Create pre-authorized batch window |

**Create Execution (Example)**:

```http
POST /v1/executions
Authorization: Bearer <api_key>
Idempotency-Key: idem-uuid

{
  "policy_id": "pol_wealth_mgmt_v2",
  "user_id": "user_123",
  "service": "schwab",
  "action": "read_balance",
  "params": {}
}
```

**Success Response (Indicative)**:

```json
{
  "execution_id": "exec_9921",
  "status": "completed",
  "data": {},
  "proof": "0x...",
  "audit_ref": "immu:aud_8821abc",
  "policy_id": "pol_wealth_mgmt_v2",
  "policy_version": 2,
  "duration_ms": 482
}
```

***

## Audit: Audit and Proof Bundles (Planned)

| Method | Path (Indicative)         | Description                                        |
| ------ | ------------------------- | -------------------------------------------------- |
| `GET`  | `/v1/audit/records`       | Filter execution audit records                     |
| `GET`  | `/v1/audit/records/:id`   | Single record                                      |
| `POST` | `/v1/audit/proof-bundles` | Export verifiable proof bundle (may be chargeable) |

Record field design target: **no** plaintext params, **no** credential values; includes `params_hash`, `execution_receipt`, `tee_mrenclave`, `hitl_proof`, etc.

***

## Webhook (HITL / Async)

* Events: `execution.pending_hitl`, `execution.completed`, `execution.failed`, etc. (per implementation).
* **Signature verification**: use `webhookSecret` from console (e.g., HMAC-SHA256 over raw body).

***

## Health Check and Remote Attestation

| Method | Path (Indicative)        | Description                      |
| ------ | ------------------------ | -------------------------------- |
| `GET`  | `/health`                | Load balancer health check       |
| `GET`  | `/v1/attestation/report` | TEE Quote (if opened to tenants) |


---

# Agent Instructions: 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:

```
GET https://docs.toani.ai/toani-control/getting-started/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.