# GraphQL API overview (/api)



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

## Endpoint and authentication [#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](/guides/api-keys).
* Introspection is disabled on the production endpoint. Use the pages below,
  which are generated from the same schema.

## First call [#first-call]

```bash
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 [#how-errors-look]

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

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

## Reference [#reference]

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

<Cards>
  <Card title="Queries" href="/api/queries" description="Read data: projects, services, deployments, templates, billing, and more." />

  <Card title="Mutations" href="/api/mutations" description="Change data: create and deploy services, manage environment variables, tokens and billing." />

  <Card title="Object types" href="/api/objects" description="What queries and mutations return." />

  <Card title="Input types" href="/api/inputs" description="What mutations and filtered queries accept." />

  <Card title="Enums" href="/api/enums" description="Fixed value sets such as service states and categories." />
</Cards>

## Good to know [#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](/ai-agents).