Getting started

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

Your API endpoint depends on the region your organization runs in. Send every request, with POST, to the API endpoint for your environment. For each production and sandbox environment’s endpoint, see ION environments.

The examples in these guides use the US endpoint, api.buildwithion.com. Replace it with your region’s endpoint.

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
Python

curl -X POST https://api.buildwithion.com/graphql \
  -H "Authorization: Bearer $ION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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 that lists parts:

cURL
Python

curl -X POST https://api.buildwithion.com/graphql \
  -H "Authorization: Bearer $ION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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 contains 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

Where to go next depends on what you’re building:

If you’re…	Go to
Building a reusable API client	Build an API client
Working through common queries and mutations	Example requests
Building real-time event-driven integrations	Set up webhooks
Uploading files, such as procedure attachments and run artifacts	Upload a file
Mapping ION’s data model into your system	Data model
Hitting a 403 or unfamiliar error	Error codes
Testing without affecting production	Sandbox
Taking an integration to production	Build a production integration

Build Hardware

Manage Supply Chain

Track Quality

Automate with ION

Administration

API

Getting started

Prerequisites

The endpoint

Get an access token

Make your first request

Query data

Pick your next page

​Prerequisites

​The endpoint

​Get an access token

​Make your first request

​Query data

​Pick your next page

​Related

Prerequisites

The endpoint

Get an access token

Make your first request

Query data

Pick your next page

Related