GraphQL

GraphQL provides read-only access to the same data as the HTTP API. Its purpose is composite reads: a single request can return several related entities, where the HTTP API returns one entity or one list per call and leaves the caller to resolve references with further calls.

There are no mutations. Create, update and delete operations are available only through the HTTP API.

Address and authentication

GraphQL is served per space:

POST https://api.eolymp.com/spaces/{space_id}/graphql

Authentication is identical to the HTTP API: the same Authorization: Bearer credential, subject to the same permissions. GraphQL is implemented on top of the HTTP API, so it cannot return data the HTTP API would refuse.

Each space exposes its own address in graphql_url. Reading it from the space is preferable to composing the URL, as it remains correct if the address layout changes.

Composite reads

curl https://api.eolymp.com/spaces/SPACE_ID/graphql \
  -H "content-type: application/json" \
  -d '{"query":"{ posts(first: 2, sort: PUBLISHED_AT, order: DESC) { totalCount nodes { id title publishedAt type { name } } } }"}'

{
  "data": {
    "posts": {
      "totalCount": 13,
      "nodes": [
        {
          "id": "vi9mlaafbl4fl7jtomsr8ccgk0",
          "title": "Achievements are live",
          "publishedAt": "2026-07-27T18:28:01Z",
          "type": {"name": "Console Updates"}
        },
        {
          "id": "lniupjninp7tr01lelhn821dgk",
          "title": "Automate the routine work in your space",
          "publishedAt": "2026-07-27T18:25:19Z",
          "type": {"name": "Console Updates"}
        }
      ]
    }
  }
}

Each post references a post type. Over HTTP that reference requires a second call per distinct type; here type { name } resolves it within the same request. The same applies to deeper structures, such as a contest with its problems and each problem with its statement.

Schema layout

The schema mirrors the HTTP API. Root fields come in pairs: a singular field taking an id, and a plural field returning a list. Examples are problem and problems, contest and contests, member and members, post and posts; submissions, issues, courses, groups, achievements, scoreboards and pages follow the same pattern.

Plural fields return connections, containing totalCount, nodes, edges for cursor access, and pageInfo:

{
  members(first: 20, search: "ivan", sort: "name", order: ASC) {
    totalCount
    nodes { id displayName }
  }
}

Arguments correspond to those of the HTTP API: first with offset or after for pagination, search, sort and order, filters for structured conditions, and extra for data omitted from a read unless requested. extra behaves as it does over HTTP, so rich content follows the rules described in Rich content: request the source or the parsed tree, and an unrequested content field is returned empty.

The schema supports introspection, so a GraphQL client or editor pointed at the address above provides completion and per-field documentation. The equivalent request:

curl https://api.eolymp.com/spaces/SPACE_ID/graphql \
  -H "content-type: application/json" \
  -d '{"query":"{ __type(name: \"Query\") { fields { name } } }"}'

Choosing between GraphQL and the HTTP API

Use GraphQL for reads spanning several related entities, and for data export. Use the HTTP API for writes, for retrieving a single entity, and where one of the SDKs is preferred, as these wrap the HTTP API.

Both interfaces expose the same data under the same permissions, so combining them in one integration is expected: reads through GraphQL, writes through HTTP.