API Introduction - Cedar.AI Documentation

The ARMS external API supports HTTP/2 and HTTP/1.1. All endpoints use HTTP POST.

Regions

Cedar’s production APIs run in two regions: US (primary, cedarai.com) and EU (cedarai.se). Same paths, same headers, same key shape — only the hostname suffix changes.

	US	EU
Hostname suffix	`cedarai.com`	`cedarai.se`
REST + gRPC HTTP/2 (ARMS)	`https://api-lg.arms.cedarai.com`	`https://api-lg.arms.cedarai.se`
gRPC HTTP/1.1 (ARMS)	`https://api-lg-k-h1.arms.cedarai.com`	`https://api-lg-k-h1.arms.cedarai.se`
Shipper APIs (Quotes/Invoices)	`https://api-lg-k.arms.cedarai.com`	`https://api-lg-k.arms.cedarai.se`
Notes (Linda)	`https://api.linda.cedarai.com`	`https://api.linda.cedarai.se`

Every other production hostname follows the same .com ↔ .se mapping — just swap the TLD.

API keys are region-scoped. A key issued for the US region won’t authenticate against an EU host (and vice versa). Use whichever region your account was provisioned in.

The per-endpoint reference pages expose a server dropdown above each “Try it” cURL snippet so you can flip between US and EU without editing the URL by hand. The base-URL blocks throughout this page are also shown as tabs for the same reason.

Staging and dev environments are US-only (.com) — there is no .se mirror for -staging or -dev hosts.

Authentication

Include the following headers on every request:

Header	Description
`x-arms-api-key`	Your API key, issued by Cedar.
`x-arms-assume-user`	Email of the Cedar user the request is acting on behalf of. Must be a member of at least one user group bound to the API key. See the linkage rules below.
`Content-Type`	`application/json`

How API keys, user groups, and assumed users link up

Cedar’s IAM model makes API keys flow permissions through a user group, not directly through individual users:

An API key is bound to one or more user groups

When the key was created, your admin attached it to one or more user groups (for example, prod-integrations). The key can only act as users that are members of those exact same groups.

The assumed user must belong to one of those bound groups

Whatever email you put in x-arms-assume-user must be a current member of at least one of the user groups bound to the API key. If the user exists but isn’t in a bound group, the request is rejected with 401.

Permissions come from the assumed user, not the key

The effective permissions for the request are the union of all roles assigned to the assumed user (via their group memberships and/or direct bindings). A valid key + valid user with no permissions on the target endpoint returns 403, not 401.

Choosing what to pass in `x-arms-assume-user`

You have two reasonable approaches, and they trade off operational simplicity against audit-trail fidelity. Pick based on whether your integration needs to attribute every action to the real human in your other system.

Option A — Service-account user (simple)
Option B — Real user pass-through (best audit trail)

Use one dedicated service-account user for all calls from a given integration (e.g. integrations@yourco.example).


How it works	Create one Cedar user, put it in one dedicated group (e.g. `api-integrations`), bind the API key to that group, assign one or more API access roles. Every API call sets `x-arms-assume-user: integrations@yourco.example`.
Pros	Zero user management — one user, one group, one role assignment. Rotating the key or adding a second integration changes nothing on the user side. Onboarding is a 5-minute Admin Portal task.
Cons	Cedar’s audit log, event history, and `created_by` fields will all read as the service account — you lose attribution to the real human in your upstream system. If you need to answer “who did this?”, you have to cross-reference your own application logs.
Best for	Background jobs, ETL, batch syncs, webhooks, or any integration where the action genuinely originates from a system rather than a user.

Pass the actual end-user’s email through x-arms-assume-user on every request — typically the user who clicked the button in your application.


How it works	Every human user of your upstream system gets a corresponding Cedar user provisioned with the right roles. Your integration captures the calling user and forwards their email in `x-arms-assume-user` per request. The API key is bound to a group that contains all of those users.
Pros	Cedar’s audit log, event history, `created_by` fields, and Notes authorship all attribute the action to the real human. Investigations and compliance reviews stay inside Cedar — no cross-system log correlation. Per-user permissions still apply, so a user without a role can’t escalate via the integration.
Cons	Every active human in your application must exist as a Cedar user and be a member of the API key’s bound group. Joiners, movers, and leavers in your IdP must keep that membership in sync, otherwise users hit 401. Manually adding everyone in the Admin Portal does not scale.
Best for	Interactive integrations where a human took the action — embedded UIs, partner portals, custom dashboards, mobile companion apps.

Use SCIM to make Option B sustainable. SCIM provisions users and group memberships into Cedar from your IdP (Okta, Azure AD, etc.) automatically — every joiner, mover, and leaver in your directory is reflected in Cedar without manual Admin Portal work. Bind your API key to a group that’s managed by SCIM (e.g. cedar-api-users), and your IdP becomes the single source of truth for who can call the API as themselves. New hires get access automatically; departing employees lose it the moment they’re deactivated upstream — no orphan service accounts, no out-of-band reviews.

Many customers run both patterns in parallel: a service-account user for system-to-system jobs, and SCIM-managed pass-through for human-driven flows in their custom apps. Bind the API key to two groups (one per pattern), assign the same API access role(s) to both, and let your client decide which email to send per request.

Need an API key? API key management is coming soon to the Admin Portal. Contact your account representative for access.

Troubleshooting `401 Unauthorized`

A 401 means Cedar couldn’t authenticate the request — the key, the assumed user, or the link between them is wrong. Run through this checklist:

API key issues

Key is expired or rotated. Ask your admin to confirm the key is still active in the Admin Portal. Rotated keys stop working immediately.
Wrong header name. Cedar expects x-arms-api-key (lowercase). Some HTTP clients normalize header casing — verify the wire format if you’re behind a proxy.
Header value contains whitespace or quotes. The key value should be raw, no Bearer prefix and no surrounding quotes.
Key was bound to a different environment. Production keys won’t work against staging URLs and vice versa.

Assumed user issues

User doesn’t exist. The email in x-arms-assume-user must match a real, active Cedar user for your carrier.
User is deactivated. Deactivated users fail auth even if the key is valid. Reactivate the user in the Admin Portal.
Email casing or typo. The lookup is case-sensitive in some flows — confirm the exact spelling against the user’s profile.
Wrong header name. Must be x-arms-assume-user (lowercase, with the dash before user, not userid).

API key ↔ user group linkage

The assumed user isn’t in any group bound to the key. This is the single most common cause. Confirm in the Admin Portal that the user belongs to at least one user group that the API key is also bound to.
The user group lost its API-key binding. Group bindings can be removed independently of the key itself. Re-attach the key to the right group.
The user was removed from the group. Adding the user back to the bound group fixes auth immediately — no key rotation required.
Group has no roles. A user that’s in the right group but has no roles assigned will pass auth (avoid 401) but every endpoint will return 403. If you’re seeing 401, the linkage itself is missing.
Real-user pass-through with stale group membership. If you’re using Option B (real users), confirm your IdP push reached Cedar — the user may exist but not yet be in the bound group. SCIM usually syncs within a minute; a manual re-push from your IdP is the fastest fix for one-off cases.

Carrier and environment issues

Wrong carrier scope. API keys are scoped to one carrier. Calling against another carrier’s data — for example, by passing a carrierId query parameter from a different carrier — fails auth.
Cross-environment or cross-region call. Confirm the base URL matches both the environment and the region the key was issued in. Production ARMS uses api-lg.arms.cedarai.com (US) / .se (EU); production Notes uses api.linda.cedarai.com (US) / .se (EU); staging/dev use the -staging / -dev variants and are US-only. See Regions for the full mapping. Keys are region-scoped — a US key against an EU host (or vice versa) returns 401.
Clock skew. If you sign or timestamp the request out of band, large clock drift can look like 401 from intermediate proxies. Sync your client clock.

Still stuck?

Capture the request id from the failing response (look for the x-arms-request-id header) and email support@cedarai.com with:

The full failing endpoint and HTTP method.
The masked x-arms-api-key (first 4 characters only) and the x-arms-assume-user email.
The response status, headers, and body.
The x-arms-request-id so support can trace the request end-to-end in our logs.

API access roles

Cedar ships a predefined system role per API section so you can grant a service account the exact permissions it needs without composing custom roles. Assign one (or more) of these to the user that your API key calls as via x-arms-assume-user.

Role	Covers	Permissions bundled
`arms.railcarApi`	Railcar API (15 endpoints)	14 (equipment list/move/notes/switch-request, charged history, toolswork, class-lists, customers list, etc.)
`arms.waybillApi`	Waybill API (1 endpoint)	1 (waybill create)
`arms.workOrderApi`	Work Order API (9 endpoints)	5 (work order list/update, task list, train work order list/recordEvent)
`arms.chargeApi`	Charges API (3 endpoints)	3 (charges list, exportCharges, viewChargesPage)
`shipping.invoiceApi`	Shipper Invoices API (3 endpoints)	3 (invoices list/get/attachVoucher)
`shipping.quoteApi`	Shipper Quotes API (1 endpoint)	1 (quotes list)
`arms.networkStructureApi`	Network Structure API (1 endpoint)	2 (grouping listThirdParty, hierarchy summary list)
`linda.notesApi`	Notes API (9 endpoints)	7 (notes create/list/edit/editAny/delete/deleteAny/search)

Each section role grants only what’s needed to call the endpoints in that section. You can combine multiple roles on one user — for example, a finance integration that exports charges and reads invoices would get arms.chargeApi + shipping.invoiceApi. For pricing-tier roles (cedar.apiBasic, cedar.apiEssential, cedar.apiProfessional), see the API pricing page.

REST endpoints

Base URL for REST endpoints

US (cedarai.com)
EU (cedarai.se)

https://api-lg.arms.cedarai.com

https://api-lg.arms.cedarai.se

Railcar API Endpoints

A high-level list of available endpoints:

Endpoint	Description	Docs
`/ims/equipment/inventory`	List railcar inventory	List railcar inventory API
`/ims/groupings/list`	List groupings for a specific carrier	List groupings API
`/ims/groupings/station-tracks`	List station tracks for a specific carrier	List groupings API
`/ims/equipment/move`	Update railcar inventory	Update railcar inventory API
`/ims/equipment/switch-request`	Submit railcar switch request	Submit railcar switch request API
`/ims/equipment/charged-history`	List railcar charge history	List railcar charge history API
`/ims/equipment/bulk-edit-charged-history`	Bulk edit charge history	Bulk edit railcar charge history API
`/ims/equipment/load-toolswork`	Toolswork: load equipment	Toolswork load equipment API
`/ims/equipment/notes/update`	Update equipment notes	Update equipment notes API

Waybill API Endpoints

A high-level list of available endpoints:

Endpoint	Description	Docs
`/ims/waybills/bill-of-lading`	Create bill of lading	Create bill of lading API

gRPC transcoded endpoints

These endpoints are sent to Envoy over HTTP and get proxied to a gRPC service.

Base URL for gRPC transcoded endpoints

If your service supports HTTP/2, use the following base URL:

US (cedarai.com)
EU (cedarai.se)

https://api-lg.arms.cedarai.com

https://api-lg.arms.cedarai.se

If your service does not support HTTP/2, use the following base URL:

US (cedarai.com)
EU (cedarai.se)

https://api-lg-k-h1.arms.cedarai.com

https://api-lg-k-h1.arms.cedarai.se

Work Order API

A high-level list of available endpoints:

Endpoint	Description	Docs
`/t/v1/arrive-train`	Arrive train	Arrive Train API
`/t/v1/depart-train`	Depart train	Depart Train API
`/t/v1/list-work-orders`	List Work Orders	List Work Orders API
`/t/v1/list-work-order-tasks`	List Work Order Tasks	List Work Order Tasks API
`/t/v1/resequence-train`	Resequence a train	Resequence Train API
`/t/v1/update-work-order`	Update a Work Order	Update Work Order API
`/t/v1/record-train-event`	Record Train Event	Record Train Event API
`/t/v1/list-train-reason-codes`	List Train Reason Codes	List Train Reason Codes API
`/t/v1/setout-cars`	Setout Cars	Setout Cars API
`/t/v1/pickup-cars`	Pickup Cars	Pickup Cars API

Network Structure API

A high-level list of available endpoints:

Endpoint	Description	Docs
`/t/v1/network-hierarchy`	Fetch the Network Hierarchy	Network Structure API

Notes API

Threaded notes on shipments, equipment, waybills, work orders, invoices, and other records. See the Notes user guide for the in-app experience these endpoints power.

The Notes API is served by Cedar’s Linda service on its own dedicated host — not the ARMS gateway base URL above. Use the base URL below for all /v1/notes/* endpoints; calls to api-lg.arms.cedarai.com/v1/notes/... will not resolve.

Base URL for Notes API

US (cedarai.com)
EU (cedarai.se)

https://api.linda.cedarai.com

https://api.linda.cedarai.se

Endpoint	Description	Docs
`/v1/notes/create`	Create a note on an entity	Create a note
`/v1/notes/update`	Update note content and references	Update a note
`/v1/notes/delete`	Soft-delete a note	Delete a note
`/v1/notes/list`	List notes on an entity (or reverse-lookup)	List notes
`/v1/notes/get-summary`	Note count + latest note for one entity	Get note summary for one entity
`/v1/notes/batch-get-summaries`	Note summaries for many entities at once	Batch get note summaries
`/v1/notes/search`	Full-text search across notes	Search notes (full-text)
`/v1/notes/summarize-entity`	AI summary of a note thread	AI summary of a note thread
`/v1/notes/search-references`	Search referenceable entities for `@`-mentions	Search referenceable entities

View OpenAPI Specs

Use the links to view and save the OpenAPI specs in JSON format.

Work Order API

JSON spec

Network Structure API

JSON spec

Shipper Invoices API

JSON spec

Shipper Quotes API

JSON spec

Notes API

JSON spec

REST API

JSON spec

Admin Portal

Manage users, groups, roles, and access

IAM Concepts

Understand identity and access management

SSO Setup

Configure single sign-on

SCIM Provisioning

Automate user provisioning

API Pricing

API pricing calculator

Glossary

Key terms explained

Documentation Index

​Regions

​Authentication

​How API keys, user groups, and assumed users link up

​Choosing what to pass in x-arms-assume-user

​Troubleshooting 401 Unauthorized

​API access roles

​REST endpoints

​Base URL for REST endpoints

​Railcar API Endpoints

​Waybill API Endpoints

​gRPC transcoded endpoints

​Base URL for gRPC transcoded endpoints

​Work Order API

​Network Structure API

​Notes API

​Base URL for Notes API

​View OpenAPI Specs

Work Order API

Network Structure API

Shipper Invoices API

Shipper Quotes API

Notes API

REST API

​Related guides

Admin Portal

IAM Concepts

SSO Setup

SCIM Provisioning

API Pricing

Glossary

Regions

Authentication

How API keys, user groups, and assumed users link up

Choosing what to pass in `x-arms-assume-user`

Troubleshooting `401 Unauthorized`

API access roles

REST endpoints

Base URL for REST endpoints

Railcar API Endpoints

Waybill API Endpoints

gRPC transcoded endpoints

Base URL for gRPC transcoded endpoints

Work Order API

Network Structure API

Notes API

Base URL for Notes API

View OpenAPI Specs

Related guides