> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iblueprint.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# iBlueprint API: tRPC over HTTP, requests, and errors

> Understand how iBlueprint's tRPC-over-HTTP API works, including the base URL, request format for queries and mutations, response envelopes, rate limits, and error codes.

iBlueprint's API is built on [tRPC](https://trpc.io), a type-safe RPC framework that runs over standard HTTP. Every procedure you call is a typed endpoint — no separate OpenAPI spec to drift out of date. This reference covers the HTTP-level conventions you need to call the API from any language or tool, including curl.

## Base URL

```
https://api.iblueprint.ai/api/trpc
```

All endpoints are relative to this base URL.

## Procedure types

tRPC has two procedure types that map to different HTTP verbs:

| Procedure type | HTTP method | When to use                                      |
| -------------- | ----------- | ------------------------------------------------ |
| `query`        | `GET`       | Read data (list, get, status)                    |
| `mutation`     | `POST`      | Write or trigger actions (create, execute, fire) |

### Calling a query

Pass input as a URL-encoded JSON string in the `input` query parameter. The value must be a JSON object with a `json` key:

```
GET /api/trpc/{router}.{procedure}?input={"json":{...your input...}}
```

### Calling a mutation

Send a `POST` request with a JSON body containing a `json` key:

```
POST /api/trpc/{router}.{procedure}
Content-Type: application/json

{"json": {...your input...}}
```

## Response envelope

Every response — success or error — is wrapped in a standard envelope:

```json theme={null}
{
  "result": {
    "data": {
      "json": {
        // your actual response data
      }
    }
  }
}
```

Extract your payload from `result.data.json`.

## Example: list your blueprints

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://api.iblueprint.ai/api/trpc/blueprint.list" \
    --data-urlencode 'input={"json":{"page":1,"limit":5}}' \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response theme={null}
  {
    "result": {
      "data": {
        "json": {
          "data": [...],
          "pagination": {
            "page": 1,
            "limit": 5,
            "total": 42,
            "totalPages": 9
          }
        }
      }
    }
  }
  ```
</CodeGroup>

## Rate limiting

The API enforces rate limits per API key. If you exceed the limit, the server returns `HTTP 429 Too Many Requests`. Back off and retry after the period indicated in the `Retry-After` header.

## Error codes

Errors use tRPC's standard error shape. The HTTP status code reflects the error class:

| HTTP status | tRPC code               | Meaning                                |
| ----------- | ----------------------- | -------------------------------------- |
| `400`       | `BAD_REQUEST`           | Invalid input — check your parameters  |
| `401`       | `UNAUTHORIZED`          | Missing or invalid API key             |
| `403`       | `FORBIDDEN`             | Valid key but insufficient permissions |
| `404`       | `NOT_FOUND`             | Resource does not exist                |
| `429`       | —                       | Rate limit exceeded                    |
| `500`       | `INTERNAL_SERVER_ERROR` | Something went wrong on our side       |

An error response looks like:

```json theme={null}
{
  "error": {
    "json": {
      "message": "Blueprint not found",
      "code": -32004,
      "data": {
        "code": "NOT_FOUND",
        "httpStatus": 404
      }
    }
  }
}
```