"""
Atheron developer API, GraphQL, version 2026-10-15. A field is never removed or changed in a way that breaks a client without first being marked @deprecated, with the date and what replaces it, at least six months before.
"""
schema {
  query: Query
  subscription: Subscription
}

"""The developer API, version 2026-10-15. Every field is a REST call too."""
type Query {
  """
  Your application as registered, for this key's environment. Needs app:read. Same as GET /api/v1/app.
  """
  app: App

  """
  Calls, errors and latency per day and bucket, for this key's environment. Needs usage:read. Same as GET /api/v1/usage.
  """
  usage(
    """1 to 90; anything else is brought within."""
    days: Int = 7
  ): Usage
}

"""
Your application as registered, for the environment the API key belongs to. The same fields as GET /api/v1/app.
"""
type App {
  """The name people see on the consent screen."""
  name: String!

  """Where the app is: development, review or live."""
  state: String!

  """confidential (a server that keeps a secret) or public (PKCE only)."""
  kind: String!

  """The quota tier: free, growth, scale or partner."""
  quota: String!

  """The environment of this key."""
  env: Environment!

  """The OAuth client ID for this environment."""
  clientId: String!

  """The redirect addresses registered for this environment."""
  redirectUris: [String!]!

  """The scopes this environment's client may ask for."""
  scopes: [String!]!

  """The scopes review approved for live."""
  approvedScopes: [String!]!

  """Your privacy policy, shown on the consent screen."""
  privacyUrl: String

  """Your homepage, shown on the consent screen."""
  homepageUrl: String

  """Client secrets and certificates in force."""
  credentials: Int!

  """Named testers on the test client."""
  testers: Int!

  """Webhooks for this environment."""
  webhooks: Int!
}

"""Which of the app's two clients a key belongs to."""
enum Environment {
  """The test client: you, your team and up to 25 named testers."""
  TEST

  """The live client, after review."""
  LIVE
}

"""
Calls, errors and latency per day and bucket. The same answer as GET /api/v1/usage.
"""
type Usage {
  """The environment of this key."""
  env: Environment!

  """How many days the answer covers, 1 to 90."""
  days: Int!

  """One row per day and bucket, oldest first."""
  usage: [UsageDay!]!
}

"""One day and bucket of calls. Days are UTC."""
type UsageDay {
  """The day, YYYY-MM-DD, UTC."""
  day: String!

  """token, userinfo, userinfo:sensitive, api, sandbox or sign-in."""
  bucket: String!

  """Requests counted. A GraphQL request counts as its cost."""
  calls: Int!

  """Of those, how many failed."""
  errors: Int!

  """Mean time taken, in milliseconds."""
  msAvg: Int

  """Longest time taken, in milliseconds."""
  msMax: Int!
}

"""
Events as they happen, over WebSocket (graphql-transport-ws). The same events as GET /api/v1/events and your webhooks.
"""
type Subscription {
  """
  Events for this key's app and environment. Needs events:read. Same as GET /api/v1/events.
  """
  events(
    """Only these kinds. All kinds when left out."""
    types: [EventType!]

    """Resume after this event id (kept 30 days)."""
    after: ID
  ): Event!
}

"""
One event, with the same five fields a webhook delivery's body carries.
"""
type Event {
  """The event's id. Send it back as after to resume."""
  id: ID!

  """The kind of event."""
  type: EventType!

  """When it was raised, ISO 8601."""
  created: String!

  """The client it concerns."""
  clientId: String!

  """What happened."""
  data: EventData!
}

"""The kinds of event, as webhooks name them."""
enum EventType {
  USER_SIGNED_IN
  CONSENT_REVOKED
  MEMBERSHIP_CHANGED
  PING
}

"""
What happened. Which fields are present depends on the type, exactly as in a webhook's data.
"""
type EventData {
  """The person, as the sub claim your app was given. Absent for ping."""
  sub: ID

  """user.signed_in: the scopes of this sign-in."""
  scopes: [String!]

  """When it happened, ISO 8601."""
  at: String
}