API integration

Use this reference to build Subgraph requests and interpret their responses. GraphOps Subgraphs exposes standard GraphQL query endpoints over HTTPS. Each endpoint is selected by Deployment CID, Graph Network Subgraph ID, or GraphOps Endpoint Alias, and authenticated with an API key that includes Subgraphs.

Endpoint patternsCopy Anchor Link

Header-authenticated endpoints:

https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>
https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>
https://subgraphs.graphops.xyz/v1/alias/<ALIAS>

Route-token endpoints:

https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>/<GRAPHOPS_API_KEY>
https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>/<GRAPHOPS_API_KEY>
https://subgraphs.graphops.xyz/v1/alias/<ALIAS>/<GRAPHOPS_API_KEY>

See Authentication to choose how to send your API key and protect it in logs.

Request envelopeCopy Anchor Link

Subgraph queries use the standard GraphQL HTTP request shape:

{
  "query": "query Pools($first: Int!) { pools(first: $first) { id } }",
  "variables": {
    "first": 5
  },
  "operationName": "Pools"
}

{  "data": {Present when the query ran    "pools": [      {        "id": "0x000024feb293b6c6c3a80a95f1f830a8746400b9"No matching entities, not an error      },      {        "id": "0x0000d36ab86d213c14d93cd5ae78615a20596505"      },      {        "id": "0x00013bffe4c38c1372a450fac78b01cb4f554781"      },      {        "id": "0x0001fcbba8eb491c3ccfeddc5a5caba1a98c4c28"      },      {        "id": "0x00024b66a38a676c0eae59126c1367ad141afa79"      }    ]  }}

RequestCopy Anchor Link

These clients send the request envelope above through an Endpoint Alias.

curl --fail-with-body --silent --show-error "https://subgraphs.graphops.xyz/v1/alias/<ALIAS>" \
  -H "Authorization: Bearer ${GRAPHOPS_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "query Pools($first: Int!) { pools(first: $first) { id token0 { symbol } token1 { symbol } } _meta { block { number hash } } }",
    "variables": { "first": 5 },
    "operationName": "Pools"
  }'

{  "data": {Present when the query ran    "pools": [      {        "id": "0x000024feb293b6c6c3a80a95f1f830a8746400b9",No matching entities, not an error        "token0": {          "symbol": "TRUMP"        },        "token1": {          "symbol": "WETH"        }      },      {        "id": "0x0000d36ab86d213c14d93cd5ae78615a20596505",        "token0": {          "symbol": "RALPH"        },        "token1": {          "symbol": "WETH"        }      },      {        "id": "0x00013bffe4c38c1372a450fac78b01cb4f554781",        "token0": {          "symbol": "Pectra"        },        "token1": {          "symbol": "WETH"        }      },      {        "id": "0x0001fcbba8eb491c3ccfeddc5a5caba1a98c4c28",        "token0": {          "symbol": "BCZ"        },        "token1": {          "symbol": "WETH"        }      },      {        "id": "0x00024b66a38a676c0eae59126c1367ad141afa79",        "token0": {          "symbol": "WETH"        },        "token1": {          "symbol": "TI"        }      }    ],    "_meta": {      "block": {        "number": 26285619,Indexed block behind the result        "hash": "0x09fffa722f278b60998290f6534850d5b2248e083ada05d332aa684f24f8302e"      }    }  }}

ResponseCopy Anchor Link

Successful GraphQL responses include data. An empty list is a valid result when no entities match:

{
  "query": "query EmptyPools { pools(first: 10, where: { id_gt: \"0xffffffffffffffffffffffffffffffffffffffff\" }, orderBy: id) { id } _meta { block { number } } }"
}

{  "data": {    "pools": [],A successful query with no matching pools    "_meta": {      "block": {        "number": 26285631Historical block served: 26,285,631      }    }  }}

Responses can include errors even when the HTTP request succeeds. Check for errors on every response:

{
  "query": "query InvalidField { notARealField }"
}

{  "errors": [Can arrive with HTTP 200    {      "message": "Cannot query field \"notARealField\" on type \"Query\".",Fix the query; retrying will not help      "locations": [        {          "line": 1,          "column": 22        }      ]    }  ]}

Response headersCopy Anchor Link

X-Deployment-CID tells you which deployment answered without changing your query. It matches _meta.deployment for the same request. An Endpoint Alias or Graph Network Subgraph ID can serve a different deployment over time: for example, after a promotion, while a new version is still being indexed, or when an Endpoint Alias falls back to a previous version. Record the header with each response when you need to know which version produced a result.

• The header is absent when GraphOps rejects the request before it reaches a deployment, such as an invalid API key or an unknown Endpoint Alias.
• For a Deployment CID endpoint, the value is the CID in the endpoint path.
• Browser clients can read the header: responses list it in Access-Control-Expose-Headers.
• Header names are case-insensitive; some HTTP clients report it as x-deployment-cid.

Error responsesCopy Anchor Link

GraphOps error responses carry a code; look it up in the gateway errors or API key errors reference.

Next stepsCopy Anchor Link