Using the GraphQL API

Using the GraphQL API

The RollerUp API is GraphQL over HTTPS. You send a query or mutation as JSON and get back a data and/or errors payload in the standard GraphQL envelope.

If your company uses RollerUp, the fastest way to explore the API is the GraphQL playground — it signs you in with your organization account, attaches your token automatically, and lets you run live queries against your own data. No local setup required.

Endpoint

POST https://api.rollerup.tech/graphql

• Method: POST
• Content-Type: application/json
• Transport: HTTPS only

Authentication

Every request must include a Bearer access token:

Authorization: Bearer <access_token>

How you get a token depends on where you’re calling from:

• Trying things out, or browsing the schema interactively — use the GraphQL playground. It signs you in with your organization account and attaches a token for you. You never see or copy the token directly.
• Server-side, mobile, or CI/CD clients — request API credentials from your RollerUp contact. Treat the token like a password: keep it on the server, rotate it on a regular schedule, and never commit it to source control or ship it inside a public client bundle.

If a request is missing a token, or the token is expired or invalid, you’ll get HTTP 401. Authentication happens before GraphQL runs, so the body is a plain error object rather than a GraphQL errors payload:

{ "error": "Authentication failed" }

Your first request

A small query that returns the signed-in user:

query Me {
  viewer {
    id
    name
    email
    company {
      name
    }
  }
}

curl

curl -sS -X POST 'https://api.rollerup.tech/graphql' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ROLLERUP_TOKEN" \
  -d '{"query":"query Me { viewer { id name email company { name } } }"}'

fetch (browser or Node)

const response = await fetch("https://api.rollerup.tech/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    query: `query Me { viewer { id name email company { name } } }`,
  }),
});
const { data, errors } = await response.json();

Request shape

{
  "query": "query Foo($id: ID!) { ... }",
  "variables": { "id": "abc123" },
  "operationName": "Foo"
}

Response shape

The server replies with the standard GraphQL envelope:

{
  "data": { ... },
  "errors": [ { "message": "...", "path": [...], "extensions": { "code": "..." } } ]
}

• A successful query returns data and HTTP 200.
• A GraphQL validation or resolver error usually still returns HTTP 200 with details under errors. Always inspect the errors array — don’t rely on the HTTP status alone.
• HTTP 401 means your token is missing, expired, or invalid. Its body is { "error": "..." }, not the GraphQL envelope.
• Other 4xx / 5xx responses indicate transport-level problems (malformed JSON, the server is unreachable, etc.).

Lists and pagination

Queries that return lists, like cars, return one page at a time, with a cursor to fetch the next. See Pagination.

Schema reference

The full schema — every type, query, mutation, and field — is browsable at API reference. It’s generated from the same SDL the API is built from, so it stays in sync with what the server accepts.

To generate types or set up editor tooling, download the schema as SDL: rollerup-schema.graphql.

Troubleshooting

• 401 Unauthorized — your token is missing, expired, or doesn’t match the API audience. Re-issue and try again.
• 429 with THROTTLED: you’ve used up your query budget. Wait for the time in retryAfterMs, then retry. See Rate limits.
• errors: [{ "message": "Cannot query field ..." }] — the field name doesn’t exist on that type; cross-check it in the schema reference.
• errors: [{ "extensions": { "code": "FORBIDDEN" } }] — your account doesn’t have access to that resource. Check with your admin.
• No response or connection reset — confirm your client is calling https://api.rollerup.tech/graphql over HTTPS and that outbound traffic to that host is allowed.

Need help?

Reach out to your RollerUp contact, or open the GraphQL playground to verify a query end-to-end against live data before you wire it into your own code.