GraphQL API Overview

The XpressAI Platform exposes a GraphQL API at /graphql. This is the primary interface for both the web frontend and external API clients.

Key Facts

• Endpoint: https://platform.ap.xpressai.cloud/graphql (the endpoint URL may vary by deployment)
• Schema source: Auto-generated from Java @GraphQLApi annotations via SmallRye GraphQL
• Frontend client: Houdini (SvelteKit GraphQL client) with fully typed queries
• Authentication: OIDC session (browser) or Bearer token (API clients)
• Coverage: Operations across 15 domains (agents, projects, jobs, skills, vector data, billing, and more)

Schema Generation Workflow

The schema flows from Java annotations through two build steps before reaching the frontend:

1. Java @GraphQLApi classes are processed by ./mvnw process-classes, which invokes the SmallRye schema generator to produce schema.graphql.
2. npm run generate-graphql (in src/main/webui) runs Houdini, which reads schema.graphql and all .gql query files to generate TypeScript types.

warning

Never edit schema.graphql by hand. It is auto-generated and will be overwritten on the next build.

Regeneration Commands

# Step 1: Generate schema.graphql from Java
./mvnw process-classes

# Step 2: Generate Houdini TypeScript types
cd src/main/webui && npm run generate-graphql

caution

Always use npm run generate-graphql instead of calling npx houdini generate directly. The npm script includes required pre-processing steps.

Authentication

The platform uses OIDC hybrid mode, supporting two authentication methods:

Method	Use Case	How It Works
OIDC session cookie	Browser (web UI)	Automatic after login via /login
Bearer token	API clients, scripts	Pass Authorization: Bearer <token> header

You can create platform tokens via the UI or using the createPlatformToken mutation.

Example Query

query {
  projects {
    id
    name
    namespace
  }
}

Example: cURL

curl -X POST https://platform.ap.xpressai.cloud/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects { id name namespace } }"}'

Example: Fetch (JavaScript)

const response = await fetch("https://platform.ap.xpressai.cloud/graphql", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `{ projects { id name namespace } }`,
  }),
});

const { data } = await response.json();
console.log(data.projects);

What's Next

• GraphQL Queries Reference -- all available queries by domain
• GraphQL Mutations Reference -- all available mutations by domain
• Agent API Headers -- authentication headers for agent-to-platform communication