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

# GraphQL and TypeScript

> Typed documents, authentication and cursor pagination.

## Endpoint and availability

Send GraphQL requests to `POST /graphql` on your configured API host. Ask your workspace administrator for the host and availability. The API and application migration are in progress; this guide does not announce a hosted release or complete dashboard/admin coverage. The [generated reference](/en/developers/graphql-reference) lists the operations present in this build.

Use the GraphQL guide and generated reference below. Apollo Sandbox is available at `/playground` on the configured API host.

The API runs Apollo Server 5 on Vercel. Its authenticated `/playground` embeds Apollo Sandbox with the schema and named queries and mutations. Apollo Studio metrics and registry checks require a separately configured GraphOS graph.

## Authentication

Send `Authorization: Bearer <token>`. Server integrations use organization API tokens. Each request intersects token scopes with the creator's current permissions and object assignments. A token cannot switch organization by supplying an ID.

Dashboard and mobile clients use a Supabase user access token. The API verifies the identity and session, then loads current membership, organization, permissions and assignments. Required MFA must be satisfied. Refresh tokens through Supabase Auth; they are not GraphQL credentials. Personal preferences require a user session and cannot be accessed by API tokens.

## Query

Replace the host and token below with your configured values. Run reads against a test workspace first.

```bash theme={null}
curl 'https://api.example.com/graphql' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  --data '{"query":"query Projects($first: Int!) { projects(first: $first) { nodes { id name } pageInfo { hasNextPage endCursor } } }","variables":{"first":50}}'
```

Use variables for input. Select only the fields needed by your integration. IDs are UUIDs, `DateTime` uses ISO 8601 with a timezone, and `Decimal` uses strings to preserve precision. Enum values such as `frei` remain unchanged across UI languages.

## Pagination and nested reads

Connections return `nodes` and `pageInfo`. Pass the last `endCursor` as `after` while `hasNextPage` is true. The default page is 50 records and the maximum is 200. Treat cursors as opaque and keep the same filters while paging. Visibility is applied before pagination, including customer unit assignments.

Nested project properties batch their reads. The query guard charges nested fan-out; requesting 200 projects with 200 properties each can exceed the query budget. Fetch narrower pages instead of repeatedly retrying a rejected operation.

## TypeScript with typed documents

External consumers use standard GraphQL tooling; there is no DealPipe SDK or
repository-generated client import. Install `graphql-request`, `graphql`,
`@graphql-codegen/cli` and `@graphql-codegen/client-preset`. Save your own
operations as `.graphql` files and generate documents and types from the exported
[schema](/assets/graphql/schema.graphql). For example, a Codegen config can use:

```ts theme={null}
import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  schema: "./schema.graphql",
  documents: ["src/**/*.graphql"],
  generates: {
    "src/gql/": {
      preset: "client",
      presetConfig: { fragmentMasking: false },
    },
  },
};
export default config;
```

Use a generated typed document with `graphql-request`. Resolve the current token
for every request and pass cancellation through its request options:

```ts theme={null}
import { GraphQLClient } from "graphql-request";
import { ListProjectsDocument } from "./gql/graphql";

const client = new GraphQLClient("https://api.example.com/graphql");

const result = await client.request({
  document: ListProjectsDocument,
  variables: { first: 50, after: null },
  requestHeaders: {
    Authorization: `Bearer ${await getCurrentAccessToken()}`,
  },
  signal: abortController.signal,
});
```

No mutation is retried automatically. After a connection failure, the server may
have completed the write; retry only when the operation has an explicit,
server-enforced idempotency contract.

## Errors and request budgets

GraphQL responses can include an `errors` array even when the HTTP status is 200. Inspect each error's message and `extensions`, and capture the `x-request-id` response header for support. `graphql-request` rejects unsuccessful GraphQL responses with its own error type; it does not promise to mask variables or other request details. Do not log raw client errors or request payloads without applying your own redaction. DealPipe's application transport has its own error masking.

The API enforces a streaming body budget, parser-token, query-depth and query-cost limits, and request rates. A budget error identifies the budget, limit and attempted value when available. Reduce fields, nested pages or batch size and split the work. Respect `Retry-After` for rate limits. Private storage URLs are signed and are returned only after visibility checks.

## Other protocols

Supabase Auth, direct uploads with authorized signed URLs and realtime channels keep their own protocols. Provider webhooks retain their HTTP methods and signature verification. These are not general application-data alternatives to the GraphQL API.

## Apollo Sandbox

Open `/playground` on your configured API host. Enter a test token and select a query or mutation. The operation catalog uses canonical example documents in `packages/graphql/operations`; each build validates its operation roots against the executable schema. Fill in required variables before running it. The page does not persist tokens or use authentication cookies. Schema introspection uses the same authenticated GraphQL API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.