Management API

The Management API lets you programmatically manage your entire Picklayer organization — it’s the API equivalent of the Builder UI dashboard. Create applications, configure keys, manage users, handle billing, and more.

Quick Start

# 1. Exchange your secret key for an org token
TOKEN=$(curl -s https://api.picklayer.ai/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'x-hasura-role: public' \
  -d '{"query":"mutation { ExchangeSecretKey(secretKey: \"sk_live_YOUR_KEY\") { data { organizationToken } } }"}' \
  | jq -r '.data.ExchangeSecretKey.data.organizationToken')
 
# 2. List your applications
curl -s https://api.picklayer.ai/v1/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ applications(where: {enabled: {_eq: true}}) { id name handler } }"}'

How it works

The Management API is the same GraphQL surface the Builder UI uses. When you sign in to the UI, it gets an organization token and calls Hasura GraphQL. The ExchangeSecretKey mutation gives agents the same token without interactive sign-in.

Builder App Setup Flow

Programmatic setup for a builder-managed app typically uses three separate surfaces:

1. Exchange an sk_* key for an organization token with ExchangeSecretKey.
2. Create or select an application and send x-hasura-application-id: <appId> on app-scoped calls.
3. Read app state from application_settings (the builder-facing view).
4. Update app settings through update_applications_by_pk on the applications table.
5. Configure runtime billing/provider state through application_runtime_configs.
6. Create related resources such as API keys, prompt endpoints, plans, files, and embeddings.

That split matters:

• application_settings is a read model.
• applications is the write surface for application settings.
• application_runtime_configs is the runtime singleton for billing mode, hosted/BYOK provider state, and runtime feature payloads.

Authentication

See API Keys for the full authentication flow and key management.

GraphQL Endpoint

URL: https://api.picklayer.ai/v1/graphql

All operations are standard GraphQL queries and mutations against Hasura. The _builder role provides full CRUD access to all organization resources, scoped by Hasura row-level security.

Available Operations

• Prompt Endpoints
• API Keys
• Relays
• Users
• Billing
• Email
• Files
• Embeddings
• Notifications
• Data Store
• Applications
• Settings
• Usage & Analytics

Machine-Readable Discovery

Python Example

import requests
 
HASURA_URL = "https://api.picklayer.ai/v1/graphql"
SECRET_KEY = "sk_live_..."
 
# Exchange key for token
resp = requests.post(HASURA_URL, json={
    "query": 'mutation { ExchangeSecretKey(secretKey: "%s") { data { organizationToken organizationId } } }' % SECRET_KEY
}, headers={"x-hasura-role": "public"})
token = resp.json()["data"]["ExchangeSecretKey"]["data"]["organizationToken"]
org_id = resp.json()["data"]["ExchangeSecretKey"]["data"]["organizationId"]
 
# List applications
resp = requests.post(HASURA_URL, json={
    "query": '{ applications(where: {organization_id: {_eq: "%s"}, enabled: {_eq: true}}) { id name handler } }' % org_id
}, headers={"Authorization": f"Bearer {token}"})
apps = resp.json()["data"]["applications"]
print(f"Found {len(apps)} applications")