GraphQL API overview

This page explains how to call the API directly. The web app, the acc CLI and the SDK all talk to this one GraphQL API, so anything they can do, a plain HTTP client can do too.

Endpoint and authentication

Endpoint: https://api.alternatefutures.ai/graphql (POST, JSON body).
Header: Authorization: Bearer <personal access token>. Create a token with acc pat create; see Access tokens.
Introspection is disabled on the production endpoint. Use the pages below, which are generated from the same schema.

First call

curl -s https://api.alternatefutures.ai/graphql \
  -H "Authorization: Bearer $AF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ projects { data { id name } } }"}'

The response lists the projects your token can see.

How errors look

Responses come back with HTTP 200 and the standard GraphQL errors array. A missing, expired or revoked token gives:

{"errors":[{"message":"Not authenticated","extensions":{"code":"UNAUTHENTICATED"}}],"data":null}

Reference

The pages below are generated from the API server's source on every merge, so they match the deployed schema.

Queries

Read data: projects, services, deployments, templates, billing, and more.

Mutations

Change data: create and deploy services, manage environment variables, tokens and billing.

Object types

What queries and mutations return.

Input types

What mutations and filtered queries accept.

Enums

Fixed value sets such as service states and categories.

Good to know

Queries are limited by complexity. Prefer flat selections with IDs over deeply nested lists, then fetch details in a second query.
These pages leave out, on purpose, provider-specific types and fields, the operations of the retired hosting product (sites, IPFS storage, functions), and admin-only operations.
For scripted work, the CLI with --json and AF_TOKEN is often simpler than hand-written GraphQL; see Docs for AI agents.