api reference

Prerequisites

• An ION organization.
• An API key for machine-to-machine integrations, or OAuth credentials for user-facing applications. For how to obtain each, see Authentication.
• A tool that can make HTTPS POST requests with JSON bodies, such as curl, httpie, or Postman.
• Familiarity with GraphQL.

New to GraphQL? See the official GraphQL documentation.

The endpoint

All API requests go to one endpoint:

POST https://api.buildwithion.com/graphql

Authenticate each request with these headers:

Authorization: Bearer <token>
Content-Type: application/json

Get an access token

If you have an API key, exchange it for a short-lived access token through your auth provider’s client-credentials grant. For a reusable pattern, see the Build an API client. If you use OAuth 2.0, complete the authorization code flow in Authenticate with OAuth 2.0. After the user signs in, your callback receives an access_token. Both paths give you a JWT string. Treat it like a password.

Make your first request

A minimal “who am I?” query confirms the token works:

• cURL

curl -X POST https://api.buildwithion.com/graphql \
  -H "Authorization: Bearer $ION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n    "query": "query { me { id name email organization { id domain } } }"
  }'

Install httpx (pip install httpx), then run:

import os
import httpx

resp = httpx.post(
    "https://api.buildwithion.com/graphql",
    headers={"Authorization": f"Bearer {os.environ['ION_TOKEN']}"},
    json={"query": "query { me { id name email organization { id domain } } }"},
)
resp.raise_for_status()
print(resp.json()["data"]["me"])

For a reusable client with retries and error handling, see the Build an API client.

A successful response looks like this:

{
  "data": {
    "me": {
      "id": 42,
      "name": "Ada Lovelace",
      "email": "ada@acme.com",
      "organization": {
        "id": 7,
        "domain": "acme.com"
      }
    }
  }
}

If the response is an errors payload instead, see Error codes and its 401 table.

Query data

Once auth works, try a domain query. Listing parts is a good first test because it touches inventory, the most common integration target:

• cURL

curl -X POST https://api.buildwithion.com/graphql \
  -H "Authorization: Bearer $ION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n    "query": "query { parts(filters: {}, first: 5) { edges { node { id partNumber description } } } }"
  }'

import os
import httpx

resp = httpx.post(
    "https://api.buildwithion.com/graphql",
    headers={"Authorization": f"Bearer {os.environ['ION_TOKEN']}"},
    json={"query": "query { parts(filters: {}, first: 5) { edges { node { id partNumber description } } } }"},
)
resp.raise_for_status()
print(resp.json()["data"]["parts"]["edges"])

The response should contain up to five parts from your org. If the response comes back empty, your org might not have parts yet. Query me again to confirm the token is valid. Then check the admin UI for data.

Pick your next page

You now have a working integration. Where to go next depends on what you’re building: