Skip to main content
The ARMS external API supports HTTP/2 and HTTP/1.1. Most endpoints use HTTP POST; each endpoint’s reference page shows its method.

​
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. 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: Cedar’s IAM model makes API keys flow permissions through a user group, not directly through individual users:
1

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.
2

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.
3

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 is rejected with 401 on REST endpoints and 403 on gRPC transcoded endpoints.

​
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.
Use one dedicated service-account user for all calls from a given integration (e.g. integrations@yourco.example).
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.

​
Getting an API key

You can create and manage API keys yourself; you do not need to contact Cedar. There are two self-service paths:
  • Cedar Data Depot → API clients. Choose the documented endpoints the key may call, the users it may assume, and an expiry date. You can rotate credentials with an overlap window, revoke them, or delete the client. Requires the Data Depot API client permissions for your carrier.
  • Admin Portal → Advanced → API Keys. Create a key bound to a user group or a single user, with an optional IP allowlist and expiration date, and revoke it when it is no longer needed. Requires API key permissions in the Admin Portal.
Both paths show the raw key only once. See Tools & API Keys for step-by-step instructions.

​
AI agents (MCP)

Coding agents (Cursor, Claude Desktop, and other MCP clients) can call the same public ARMS APIs documented here through Cedar’s Model Context Protocol endpoint at https://mcp.arms.cedarai.com/mcp. Sign in with your Cedar account via OAuth — there is no separate MCP API key. This /mcp public-API connector uses pass-through IAM: each tool call succeeds or fails with the same ARMS permissions as the signed-in user. There are no named MCP access configs and no separate per-user operation allowlist for this connector. It is read-only (list/get/search); create, update, move, and delete through these public APIs stay in the ARMS UI. A separately provisioned Cedar Flow MCP resource has its own authorization and availability; connecting to /mcp does not enable it. When a user connects this endpoint from ChatGPT (or another MCP client), that client receives the JSON returned by each tool. Cedar minimizes inventory, customer, waybill, and note results before returning them to the client. See MCP data handling for what those tools omit and what operational data remains. Carrier admins can review which public operations a user can see under Cedar Data Depot → MCP → Permissions. That tab shows existing ARMS access; it does not create a second grant list.
If you do not see the MCP tab in Data Depot, ask your Cedar account team to grant Data Depot access for your carrier.

​
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.
  • 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).
  • 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 but is rejected by every endpoint: 403 on gRPC transcoded endpoints, 401 on REST endpoints. On a gRPC transcoded endpoint, a 401 means 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.
  • 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.
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.
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

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

​
Railcar API Endpoints

A high-level list of available endpoints:

​
Reporting wagon damage

POST /ims/equipment/wagon-damage takes each wagon’s complete set of open defects (wagonNumber plus defects, each with defectCode, defectDescription, defectRemark and a defectSeverity of red, blue or white). Up to 500 wagons per request. It needs inventoryManagement.equipment.updateThirdParty (included in arms.railcarApi).
  • Each message replaces what ARMS shows for that wagon. Send every open defect each time, not just the new one.
  • An empty defects list means the wagon is repaired.
  • Resending is safe. A wagon whose defects already match what ARMS shows is a no-op: nothing is written, no automation runs, and its entry in items has changed: false.
  • All or nothing. If any wagon fails validation the request returns 400 and nothing is stored. A missing permission returns 401.
  • equipmentKnown in each items entry is true when the wagon is in your inventory; defects for other wagons are still stored and appear as soon as the wagon arrives.
See Report wagon damage API for the full schema and examples.

​
Waybill API Endpoints

A high-level list of available endpoints:
Shipments that cross the US–Mexico border have additional required fields beyond the base schema. See Cross-border (Mexico) waybills before calling /ims/waybills/bill-of-lading for a MX origin or destination.

​
Emptying cars

POST /ims/equipment/empty-equipment marks cars empty the way the Empty button in ARMS does. Name each car by initialAndNumber (for example "MGLX 5493") or equipmentId, up to 500 per request. It needs inventoryManagement.equipment.emptyThirdParty (included in arms.waybillApi).
  • The empty waybill comes from the car’s loaded waybill. Shipper and consignee are swapped, the route is reversed, the commodity is kept as last contained, and the waybill is non-revenue. Its origin is the car’s current station.
  • Resending is safe. A car that is already empty is left as it is, and its entry in items has changed: false.
  • The car must be on a loaded waybill. A car whose current waybill is not loaded, or that is not at a station with an FSAC, returns 412. Cars carrying containers return 400.
  • All or nothing. Any error writes nothing. A missing permission returns 401.
  • Don’t empty cars with create bill of lading. It ignores loadStatus and creates a new waybill with no parties, commodity or route.
See Empty equipment API for the full schema and examples.

​
Customer API Endpoints

Create and update the customers you serve or bill, for example to keep ARMS in step with the customer master in an ERP such as NetSuite. To find existing customers and their IDs, use List customers in the Railcar API.

​
Keeping customers in sync

  • Store the IDs Cedar returns. Create customer returns the resourceId of the customer and of each location and address, and Update customer needs them. There is no upsert by your own ID; you can keep your ID on each location in externalLocationId.
  • Names are unique. Customer names and SCACs are unique per carrier, and location names per customer: a duplicate returns 400. Before retrying a create that timed out, look the name up with List customers.
  • List customers returns only part of a customer. It leaves out ediId, isTaxExempt, and each location’s isDefault, usedForBilling, externalLocationId, contact details and address. Keep the full record that create and update return, including address resourceIds, and treat your system as the source of truth for those fields.
  • Send each location you change in full, including isDefault and its address. Location fields you leave out are reset or cleared. Locations you leave out of the request are not changed. To add a location, leave out its resourceId and set customerId.
  • Name your own carrier. The body’s carrier, and each location’s carrier if you send one, must be the carrier in the carrierId query parameter, named by resourceId; anything else returns 401. A location you send without a carrier takes the customer’s.
  • Some invalid requests return 500, not 400: an address missing streetLine1, city, state or zipCode, and a changed location sent without its address. Fix the request rather than retrying it.
  • New customers get user groups. Cedar creates <name> Admin and <name> Operator user groups for each new customer. Renaming the customer renames them as the user in x-arms-assume-user; if that user cannot update user groups, the rename can fail, so rename the customer in ARMS instead.
  • Renames update references. Renaming a customer or location also updates clear references to the old name in revenue agreements, invoice settings, and workflows, as renaming it in ARMS does.
Both endpoints are covered by the arms.customerApi role. The API does not delete customers; delete them in ARMS.

​
Service Type API Endpoints

Service types say what a charge is for, such as switching or storage. Accounting integrations map each one to an item in NetSuite or QuickBooks. These endpoints list and maintain service types; prices live in rate tables, which this API does not change.
  • Names are unique per contextType. A carrier can’t have two service types with the same name and contextType (INCIDENTAL, CYCLE or EXCESS), even if one was deleted in ARMS. New carriers start with default service types such as Demurrage and Storage. A duplicate create returns 400: list first and update the match instead. A deleted match can’t be restored through the API; list with getDeleted: true to find it, and restore it in ARMS.
  • Update replaces the whole service type. Send every field of item, including the ones you are not changing. The one exception is defaultGlCode. It was added later, so an update that leaves it out keeps the code set in ARMS. Send null to clear it.
All four endpoints are covered by the arms.serviceTypeApi role. The API does not delete service types.

​
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:
https://api-lg.arms.cedarai.com
If your service does not support HTTP/2, use the following base URL:
https://api-lg-k-h1.arms.cedarai.com

​
Work Order API

A high-level list of available endpoints:

​
Bookings API

The Bookings API returns expected stops from bookings, including reservations without assigned equipment, matching the ARMS Bookings (beta) screen. One response item represents one expected stop, not one booking number. Set hasEquipment to false to return booking reservations without assigned equipment, true to return assigned bookings, or omit it to return both. The default page size is 100 and the maximum is 200. Use the opaque page.nextToken from each response as page.nextToken on the next request, keeping the filters and pageSize unchanged. Stop when the token is absent or empty.
Equipment, current-track, and current-station filters only match bookings with assigned equipment. To filter booking-only reservations by a Cedar station, obtain grouping IDs from the Network Structure API and pass them in attributeFilter.stationGroupingIds. Results also honor the assumed user’s geographic access.

​
Network Structure API

A high-level list of available endpoints:

​
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

https://api.linda.cedarai.com

​
View OpenAPI Specs

Use the links to view and save the OpenAPI specs in JSON format.⁠​‌​‌​​‌‌‌‌​‌​‌‌‌‌​‌‌​‌​​⁠ If you are not signed in to docs.cedarai.com, the links take you to the Cedar sign-in page first.

Bookings API

JSON spec

Work Order API

JSON spec

Charges API

JSON spec

Network Structure API

JSON spec

Shipper Invoices API

JSON spec

Shipper Quotes API

JSON spec

Truck Load Tender 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