API overview

JustAI has three data APIs. The Identify API creates and updates customer profiles. The Track API records customer events. The Profiles API reads one customer profile back. All three use the same host, the same API keys, and the same rules for organizations and environments.

A customer profile is one person and the traits you know about them, such as their email address and plan. An event is one action that a person took, such as completing an order. Key concepts explains how profiles and events fit together.

Base URL

Every request goes to this host:

https://ingest.justwords.ai

The API host is on justwords.ai, not on getjust.ai like this docs site.

Endpoints

Method	Path	API	What it does	Success status
POST	/api/identify/{org_slug}	Identify API	Creates or updates one customer profile	200
POST	/api/track/{org_slug}	Track API	Records one customer event	202
GET	/api/profiles/{org_slug}/{user_id}	Profiles API	Reads one customer profile	200

There is no batch, alias, group, page, or screen endpoint. The paths are not Segment’s HTTP Tracking API, so a Segment SDK or library cannot send to them directly. Use a tool or destination that sends one request per profile update or event. Choose a data source compares the options.

Authentication

Every request needs a JustAI API key. To create one, open the account menu at the bottom of the left sidebar, select Settings > API keys, and select New key. Key creation works after your JustAI team turns on API access for your organization. Credentials covers creating, rotating, and revoking keys.

Send the key in one of three ways:

Method	Header	Use it when
API key header (recommended)	X-Api-Key: YOUR_API_KEY	Your tool lets you set a custom header.
Bearer token	Authorization: Bearer YOUR_API_KEY	Your tool supports only bearer authentication.
HTTP Basic	Authorization: Basic followed by the Base64 encoding of YOUR_API_KEY:	Your tool asks for a write key, or for a username and password. Enter the key as the username. JustAI ignores the password.

JustAI reads the key in this order:

1. If X-Api-Key has a value, JustAI checks only that key. A wrong X-Api-Key returns 401, even when the Authorization header holds a valid key.
2. If X-Api-Key is absent or blank, JustAI reads the key from the Authorization header.

Two properties of every key matter for these APIs:

• Each key belongs to one environment, the one selected when the key was created. See Environments.
• Keys have no per-API scopes. One key works with every supported JustAI API in its environment, so treat each key as a full-access server secret.

Organization slug

The {org_slug} in each path is your organization slug. It identifies your organization in API paths and is different from your organization’s display name. Your JustAI team gives you the slug at kickoff.

You can also find the slug in JustAI:

• On your Iterable connection in Settings > Integrations. The system webhook endpoint and the content data feed URL both contain it, in the path segment right after /webhooks/iterable/. Check this while Production is selected.
• In your browser’s address bar after org=, while you use JustAI.

A slug follows these rules:

• It contains lowercase letters, digits, and hyphens. Path values for non-production environments can also contain underscores.
• It has 1 to 63 characters.
• It starts and ends with a letter or a digit.

A path value that breaks these rules, including one with an uppercase letter, returns 400 with {"error":"Invalid org slug"}.

Environments

An environment is a separate space for data and settings in your organization, such as Production or Staging. Each one has its own customer profiles, events, journeys, integrations, and API keys. Every organization has a Production environment, and your organization can add others for testing.

A request reaches the environment named by its path value and its X-JustAI-Environment header. The API key must belong to that same environment.

Environment	Path value	X-JustAI-Environment header	API key
Production	Your organization slug, for example acme	Leave it out, or send prod	Created while Production is selected
Any other environment	The environment’s path value, for example acme_staging	The environment key, for example staging	Created while that environment is selected

Your JustAI team gives you the path value and the environment key for each non-production environment. While a non-production environment is selected in JustAI, your browser’s address bar also shows its environment key after env=.

These rules apply to every request:

• prod is the only header value for Production. production returns 403.
• An empty value, Prod, a value longer than 32 characters, or a value with characters other than lowercase letters, digits, and hyphens returns 400 with {"error":"Invalid environment"}.
• A key works only in its own environment. A mismatch between the key, the path value, and the header returns 403 with {"error":"Forbidden"}. A non-production key never writes to Production.
• Requests to an environment that your organization removed return 403, even with a valid key.

To create a key for a non-production environment, switch to that environment first. Open the account menu, select Environment, and select Switch next to the environment. Then create the key in Settings > API keys. The page description names the environment, for example “API keys for the Staging environment.”

A request to a non-production environment looks like this:

POST https://ingest.justwords.ai/api/track/acme_staging
X-Api-Key: YOUR_API_KEY
X-JustAI-Environment: staging
Content-Type: application/json

Request format

• Send exactly one JSON object in each POST body. An array, or a Segment-style {"batch": [...]} envelope, returns 400.
• Send Content-Type: application/json.
• Send IDs as strings.
• Send timestamps as ISO 8601 strings with Z or a numeric offset, such as 2026-10-01T12:00:00Z. Epoch numbers and SQL-style values such as 2026-10-01 12:00:00 return 400.
• JustAI ignores top-level fields that it does not use, such as sentAt and receivedAt. A single Segment or RudderStack track call works unchanged. An identify call works unchanged when it has a userId and top-level traits.

The shell examples in this reference read your organization slug and API key from the JUSTAI_ORG_SLUG and JUSTAI_API_KEY environment variables. Test your connection shows how to set them.

Paths must match exactly

JustAI matches each path and method exactly. A trailing slash, a different method, or an unknown path returns 404 with the plain-text body 404 Not Found. For example, POST /api/track/acme/ and GET /api/track/acme both return 404. Enter endpoint URLs in your tools without a trailing slash.

Call the APIs from your servers

Send requests from your backend, your CDP, or your warehouse tool. Never put an API key in browser, mobile, or other client-side code. The APIs send no CORS headers, and a browser’s preflight OPTIONS request returns 404, so calls from a web page fail.

Size limits

The Track API has these limits:

Limit	Result when exceeded
Each event must be under about 1 MB. JustAI counts a larger size than your request body.	413 with {"error":"Track event is too large"}
An event that starts or advances a journey must keep its properties and IDs under 128 KB, with properties nested no more than 100 levels deep.	JustAI accepts the event and counts it for analytics, but the event does not trigger a journey.

The size JustAI counts is larger than your request body, especially when properties, context, or integrations contain many quotes. Keep each event well under 1 MB.

The Identify API does not enforce a size limit. Keeping each request under 1 MB is conservative guidance, not an enforced contract. Confirm larger payloads with your JustAI team. Keep traits flat, because a nested object replaces the whole stored value of its trait.

Rate limits

JustAI does not publish a fixed rate limit. JustAI can slow or block unusually heavy traffic.

• Send one request per profile update or event.
• Keep concurrency moderate. For a profile backfill, 10 concurrent requests or fewer is a conservative suggested starting point, not an enforced limit. Confirm it with your JustAI team. Before the first full run, send your JustAI team the number of profiles and your planned concurrency. See Load your existing customers.
• Don’t replay past events through the Track API. A replayed event whose name matches a published journey starts it. Contact your JustAI team before planning an import of past events.
• Treat a 429, any 5xx, or a timeout as temporary. Retry with exponential backoff and jitter, and keep the same body and messageId. Errors and retries has the full policy.

Response conventions

Responses are JSON, except the plain-text 404 Not Found for an unknown path or method. Each API has its own success status and body:

API	Status	Body
Identify	200	{"success":true,"messageId":"...","duplicate":false}
Track	202	{"message_id":"...","status":"accepted"}
Profiles	200	The profile, with org_slug, user_id, profile_id, updated_at, and fields

• Field names differ by API. The Identify response uses messageId. The Track response uses message_id. The Profiles response uses snake case.
• Times in responses are epoch milliseconds, such as "updated_at": 1790856000000.
• Every JSON error has an error string. Identify validation errors add an issues array. See Error body shapes.

Check your credentials

Read a profile to confirm that your key, organization slug, and environment work together. The request changes no data.

curl -i "https://ingest.justwords.ai/api/profiles/$JUSTAI_ORG_SLUG/user-1234" \
  -H "X-Api-Key: $JUSTAI_API_KEY"

For a non-production environment, set JUSTAI_ORG_SLUG to the environment’s path value and add -H "X-JustAI-Environment: staging" with your environment key.

The expected result is 200 with a profile, or 404 with this body:

Response

{"error":"Profile not found"}

Either result means that JustAI accepted your credentials. A 400, 401, or 403 points to the slug, the key, or the environment. Find the cause in Errors and retries.

Next steps

Identify APICreate and update customer profiles.

Track APIRecord customer events.

Errors and retriesStatus codes, retries, and duplicate handling.