> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cedarai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> REST and gRPC APIs for Cedar ARMS — railcar inventory, waybills, work orders, and network structure.

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

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

<Info>
  **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.
</Info>

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.

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

## 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Tabs>
  <Tab title="Option A — Service-account user (simple)">
    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](#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.                                                                                                                            |
  </Tab>

  <Tab title="Option B — Real user pass-through (best audit trail)">
    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.                                                                                                                                                                                 |
  </Tab>
</Tabs>

<Info>
  **Use SCIM to make Option B sustainable.** [SCIM](/user-docs/sso/scim/overview) 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.
</Info>

<Tip>
  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.
</Tip>

<Tip>
  Need an API key? API key management is coming soon to the [Admin Portal](/user-docs/admin/tools-api-keys). Contact your account
  representative for access.
</Tip>

### 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:

<AccordionGroup>
  <Accordion title="API key issues" icon="key" defaultOpen>
    * **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.
  </Accordion>

  <Accordion title="Assumed user issues" icon="user-xmark">
    * **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`).
  </Accordion>

  <Accordion title="API key ↔ user group linkage" icon="link-slash">
    * **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](/user-docs/sso/scim/overview) usually syncs within a minute; a manual re-push from your IdP is the fastest fix for one-off cases.
  </Accordion>

  <Accordion title="Carrier and environment issues" icon="building">
    * **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](#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.
  </Accordion>

  <Accordion title="Still stuck?" icon="lifebuoy">
    Capture the **request id** from the failing response (look for the `x-arms-request-id` header) and email [support@cedarai.com](mailto: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.
  </Accordion>
</AccordionGroup>

## 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](#railcar-api-endpoints) (15 endpoints)         | 14 (equipment list/move/notes/switch-request, charged history, toolswork, class-lists, customers list, etc.) |
| `arms.waybillApi`          | [Waybill API](#waybill-api-endpoints) (1 endpoint)           | 1 (waybill create)                                                                                           |
| `arms.workOrderApi`        | [Work Order API](#work-order-api) (9 endpoints)              | 5 (work order list/update, task list, train work order list/recordEvent)                                     |
| `arms.chargeApi`           | [Charges API](#api-documentation) (3 endpoints)              | 3 (charges list, exportCharges, viewChargesPage)                                                             |
| `shipping.invoiceApi`      | [Shipper Invoices API](#api-documentation) (3 endpoints)     | 3 (invoices list/get/attachVoucher)                                                                          |
| `shipping.quoteApi`        | [Shipper Quotes API](#api-documentation) (1 endpoint)        | 1 (quotes list)                                                                                              |
| `arms.networkStructureApi` | [Network Structure API](#network-structure-api) (1 endpoint) | 2 (grouping listThirdParty, hierarchy summary list)                                                          |
| `linda.notesApi`           | [Notes API](#notes-api) (9 endpoints)                        | 7 (notes create/list/edit/editAny/delete/deleteAny/search)                                                   |

<Tip>
  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](/user-docs/api-reference/pricing) page.
</Tip>

## REST endpoints

### Base URL for REST endpoints

<Tabs>
  <Tab title="US (cedarai.com)">
    ```
    https://api-lg.arms.cedarai.com
    ```
  </Tab>

  <Tab title="EU (cedarai.se)">
    ```
    https://api-lg.arms.cedarai.se
    ```
  </Tab>
</Tabs>

### Railcar API Endpoints

A high-level list of available endpoints:

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

### 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](/api-reference/create-bill-of-lading) |

<Info>
  Shipments that cross the US–Mexico border have additional required fields beyond the base schema. See [Cross-border (Mexico) waybills](/user-docs/api-reference/cross-border-mexico) before calling `/ims/waybills/bill-of-lading` for a MX origin or destination.
</Info>

## 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:

<Tabs>
  <Tab title="US (cedarai.com)">
    ```
    https://api-lg.arms.cedarai.com
    ```
  </Tab>

  <Tab title="EU (cedarai.se)">
    ```
    https://api-lg.arms.cedarai.se
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="US (cedarai.com)">
    ```
    https://api-lg-k-h1.arms.cedarai.com
    ```
  </Tab>

  <Tab title="EU (cedarai.se)">
    ```
    https://api-lg-k-h1.arms.cedarai.se
    ```
  </Tab>
</Tabs>

### Work Order API

A high-level list of available endpoints:

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

### Network Structure API

A high-level list of available endpoints:

| Endpoint                  | Description                 | Docs                                                                                      |
| ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
| `/t/v1/network-hierarchy` | Fetch the Network Hierarchy | [Network Structure API](/api-reference/networkstructureservice/get-the-network-hierarchy) |

### Notes API

Threaded notes on shipments, equipment, waybills, work orders, invoices, and other records. See the [Notes user guide](/user-docs/arms/ops/notes) for the in-app experience these endpoints power.

<Info>
  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.
</Info>

#### Base URL for Notes API

<Tabs>
  <Tab title="US (cedarai.com)">
    ```
    https://api.linda.cedarai.com
    ```
  </Tab>

  <Tab title="EU (cedarai.se)">
    ```
    https://api.linda.cedarai.se
    ```
  </Tab>
</Tabs>

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

## View OpenAPI Specs

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

<CardGroup cols={3}>
  <Card title="Work Order API" href="https://docs.cedarai.com/api-reference/work_order.swagger.json" icon="file-code">
    JSON spec
  </Card>

  <Card title="Network Structure API" href="https://docs.cedarai.com/api-reference/network_structure.swagger.json" icon="file-code">
    JSON spec
  </Card>

  <Card title="Shipper Invoices API" href="https://docs.cedarai.com/api-reference/invoices.swagger.json" icon="file-code">
    JSON spec
  </Card>

  <Card title="Shipper Quotes API" href="https://docs.cedarai.com/api-reference/quotes.swagger.json" icon="file-code">
    JSON spec
  </Card>

  <Card title="Notes API" href="https://docs.cedarai.com/api-reference/service.swagger.json" icon="file-code">
    JSON spec
  </Card>

  <Card title="REST API" href="https://docs.cedarai.com/api-reference/external-openapi.json" icon="file-code">
    JSON spec
  </Card>
</CardGroup>

## Related guides

<CardGroup cols={2}>
  <Card title="Admin Portal" href="/user-docs/admin/overview" icon="shield-check">
    Manage users, groups, roles, and access
  </Card>

  <Card title="IAM Concepts" href="/user-docs/iam/overview" icon="shield">
    Understand identity and access management
  </Card>

  <Card title="SSO Setup" href="/user-docs/sso/overview" icon="lock">
    Configure single sign-on
  </Card>

  <Card title="SCIM Provisioning" href="/user-docs/sso/scim/overview" icon="rotate">
    Automate user provisioning
  </Card>

  <Card title="API Pricing" href="/user-docs/api-reference/pricing" icon="dollar-sign">
    API pricing calculator
  </Card>

  <Card title="Glossary" href="/user-docs/admin/glossary" icon="book">
    Key terms explained
  </Card>
</CardGroup>