> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/graphql.md).

# GraphQL

Read the same escrow data with field selection over a single POST endpoint.

The same escrow data available over REST is also queryable through a single GraphQL endpoint, with the same authentication, the same roles, and the same visibility rules.

{% hint style="info" %}
GraphQL opens no door that REST does not. It exists to save round trips, not to expose more data.
{% endhint %}

### **Headers**

<table><thead><tr><th width="366">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr><tr><td>x-api-key</td><td><code>&#x3C;token></code></td></tr></tbody></table>

### Open API

## POST /graphql

Always `POST`, always the same path — including for queries.

***

### When to use it instead of REST

Use GraphQL when a screen needs several related things at once. Over REST, an escrow detail view with milestones, financials and recent events is four requests. In GraphQL it is one, returning only the fields you name.

Use REST when you want one specific thing, or when a simple cache layer matters more than round trips.

***

### Queries

| Query                | Returns                  |
| -------------------- | ------------------------ |
| `escrows(filters…)`  | A paginated `EscrowPage` |
| `escrow(contractId)` | A single escrow          |
| `ping`               | Liveness check           |

The filter vocabulary matches `GET /escrows` exactly, and the page envelope is the same `{ data, hasMore, nextCursor }`.

***

### **What this Endpoint returns?**

A standard GraphQL envelope. Note the error behaviour:

{% hint style="danger" %}
**GraphQL always returns HTTP 200, even on failure.** Check `body.errors` before reading `body.data`. The `extensions.code` values are the same vocabulary as REST Problem Details.
{% endhint %}

```json
{
  "data": { "escrow": { } },
  "errors": [
    { "message": "…", "extensions": { "code": "ESCROW_NOT_FOUND" } }
  ]
}
```

***

### Limits

| Guardrail           | Value                                                       |
| ------------------- | ----------------------------------------------------------- |
| Maximum query depth | 8                                                           |
| Maximum complexity  | 1000 fields                                                 |
| Introspection       | Disabled in production                                      |
| Mutations           | **None — GraphQL is read-only.** Every write stays on REST. |

***

### Use Example:

```typescript
import axios from "axios";

const http = axios.create({
  baseURL: "https://beta.api.trustlesswork.com",
  timeout: 10000,
  headers: {
    "Content-Type": "application/json",
    "x-api-key": your_api_key,
  },
});

const GET_ESCROW = `
  query GetEscrow($contractId: String!) {
    escrow(contractId: $contractId) {
      contractId
      status
      balance
      asset { name decimals }
      financial {
        totalDeposited
        totalReleased
        pendingRelease
      }
      milestones {
        description
        status
        approvals { target approvalCount }
      }
      events(limit: 10) {
        type
        ledger
        txHash
      }
    }
  }
`;

export const useExample = async (contractId: string) => {
  const response = await http.post("/graphql", {
    query: GET_ESCROW,
    variables: { contractId },
  });

  // GraphQL reports failures in the body, not the HTTP status.
  if (response.data.errors?.length) {
    throw new Error(response.data.errors[0].extensions?.code ?? "GRAPHQL_ERROR");
  }

  return response.data.data.escrow;
};
```

### Listing with pagination

```typescript
const LIST_ESCROWS = `
  query ListEscrows($participant: String, $limit: Int, $cursor: String) {
    escrows(participant: $participant, limit: $limit, cursor: $cursor) {
      data { contractId status balance updatedAt }
      hasMore
      nextCursor
    }
  }
`;
```

The same cursor rules as REST apply: keep the sort and order stable while paging.


---

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/graphql.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.