GraphQL and TypeScript

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 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.

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. For example, a Codegen config can use:

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:

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.

​Endpoint and availability

​Authentication

​Query

​Pagination and nested reads

​TypeScript with typed documents

​Errors and request budgets

​Other protocols

​Apollo Sandbox