# Alvys: English API Documentation v1.0

## v1.0

- [English / API Documentation / v1.0 / API Reference (103 pages)](https://docs.alvys.com/_llms/en/api-documentation/v1-0/api-reference.txt): Documentation for English / API Documentation / v1.0 / API Reference.

### Home

- [Alvys API](https://docs.alvys.com/en/api/index.md): Alvys Public API v1.0 documentation for logistics and transportation management, covering loads, drivers, authentication, webhooks, and MCP tools.

### Guides

#### Documentation

- [Alvys developer documentation overview](https://docs.alvys.com/en/api/guides/overview.md): Start here to explore Alvys Public API guides, authentication, versioning, rate limits, webhooks, and integration references for developers.
- [Getting Started with Alvys](https://docs.alvys.com/en/api/guides/getting-started.md): Get started with the Alvys Public API: create client credentials, request an OAuth access token, and make your first authenticated API call.
- [Authenticate with the Alvys Public API](https://docs.alvys.com/en/api/guides/authentication-1.md): Authenticate with the Alvys Public API using the OAuth 2.0 Client Credentials flow, including creating client apps, requesting tokens, and scopes.
- [Public roadmap](https://docs.alvys.com/en/api/guides/public-roadmap.md): Track Alvys initiatives currently in development, view features moving toward release, and follow the live public roadmap embedded from Notion.
- [Need more support?](https://docs.alvys.com/en/api/guides/need-more-support.md): Reach the Alvys Support team from the in-app Intercom widget, review past conversations, check system status, and see support hours and response times.

#### API Features

- [Base URL](https://docs.alvys.com/en/api/guides/base-url.md): Production base URL, path format, and version segment used for all Alvys Public API HTTP requests to integrations.alvys.com endpoints.
- [Versioning](https://docs.alvys.com/en/api/guides/versioning.md): How the Alvys Public API uses semantic versioning, the current v1.0 release, and how to include the version segment in your API request paths.
- [Dates & Timestamps](https://docs.alvys.com/en/api/guides/dates-timestamps.md): How the Alvys API represents dates, timezone-aware datetimes, and UTC datetimes using the RFC 3339 string format, with serialization examples for each type.
- [Rate Limits](https://docs.alvys.com/en/api/guides/rate-limits.md): Global per-token and per-organization request limits for the Alvys Public API, endpoint-specific caps, and how to handle HTTP 429 too-many-requests errors.
- [Response Codes](https://docs.alvys.com/en/api/guides/response-codes.md): HTTP status codes returned by the Alvys Public API — 2XX success, 4XX client errors, and 5XX server errors — with descriptions of each error code.
- [Idempotency](https://docs.alvys.com/en/api/guides/idempotency.md): Retry a create safely on the Alvys Public API with ExternalId, how keys are compared, and why a 503 on a keyed create means retry.
- [Updating Records Safely](https://docs.alvys.com/en/api/guides/concurrency.md): ETags and the If-Match header on the Alvys Public API — how PATCH preconditions work, what 412 and 428 mean, and how to handle a concurrent edit.
- [Currency and Money Fields](https://docs.alvys.com/en/api/guides/currency.md): How the Alvys Public API represents money — the Amount and Currency pair, the ISO 4217 numeric code, decimal precision, and how signs carry meaning.
- [Timestamps](https://docs.alvys.com/en/api/guides/timestamps.md): How the Alvys API returns UTC timestamps in ISO 8601 / RFC 3339 format and when localized stop-time values with timezone offsets are used instead.

#### AI & Agents

- [Alvys MCP server for AI agents](https://docs.alvys.com/en/api/guides/mcp.md): Connect AI agents directly to Alvys through the Model Context Protocol (MCP) server — a governed, authenticated gateway to the Alvys Public API.
- [Available MCP Tools](https://docs.alvys.com/en/api/guides/available-mcp-tools.md): Catalog of tools exposed by the Alvys MCP server, grouped by domain (loads, drivers, trips, invoices) with tier, scope, and permission requirements.

#### Use Cases

- [Connecting to Google Sheets](https://docs.alvys.com/en/api/guides/alvys-data-import-template-quick-setup-guide.md): Import live Alvys loads, trips, customers, drivers, carriers, and invoices into Google Sheets using the Public API template, with no coding required.
- [EDI integrations](https://docs.alvys.com/en/api/guides/edi-integrations.md): Connect external EDI providers to Alvys by mapping EDI 204, 214, 210, and 990 transactions to Alvys tender REST endpoints and webhook events.

##### Connecting to Power BI

- [Connecting to Power BI](https://docs.alvys.com/en/api/guides/connecting-power-bi-to-alvys-public-api-guide.md): Connect Power BI to the Alvys Public API using POST search endpoints for advanced filtering, dynamic queries, and reporting on loads, drivers, and more.
- [Authentication and Global Permissions](https://docs.alvys.com/en/api/guides/authentication-2.md): Configure Power BI parameters, retrieve an Alvys API access token, and set global permissions so subsequent queries authenticate against the Public API.
- [Create Power BI queries against the Alvys API](https://docs.alvys.com/en/api/guides/create-queries-and-retrieve-data-from-the-alvys-api.md): Build Power BI M queries that call Alvys search endpoints like loads, drivers, and fuel to pull filtered records with your access token for reporting.
- [Power BI Template File: Fast Setup Guide](https://docs.alvys.com/en/api/guides/power-bi-template-file-fast-setup-guide.md): Fast-setup guide for the Alvys Public API.pbix template — load prebuilt queries, sample reports, and parameters into Power BI Desktop in minutes.

### Webhooks

#### Getting Started

- [Webhooks overview](https://docs.alvys.com/en/api/reference/webhooks/overview.md): Configure Alvys webhooks: subscribe to events, verify endpoint ownership, validate HMAC signatures, handle retries, and manage subscriptions via API.
- [Webhook Lifecycle & Configuration](https://docs.alvys.com/en/api/reference/webhooks/webhook-lifecycle-configuration.md): Create, configure, and manage Alvys webhook subscriptions per Subsidiary, including event selection, Include Previous Values, and lifecycle states.

#### Delivery & Security

- [Event Delivery & Reliability](https://docs.alvys.com/en/api/reference/webhooks/event-delivery-reliability.md): How Alvys delivers webhook events with at-least-once semantics, unique event IDs, automatic retries on transient failures, and handling of duplicate deliveries.
- [Security & Signature Verification](https://docs.alvys.com/en/api/reference/webhooks/security-signature-verification.md): Validate incoming Alvys webhook deliveries by verifying HMAC-SHA256 signatures over the raw request body, plus HTTPS and TLS transport requirements.

#### Events

- [Load Events](https://docs.alvys.com/en/api/reference/webhooks/load-events.md): Reference for Alvys load webhook events, including load.status.changed and load.changed, event payloads, and optional data.diff field-level changes.
- [Trip Events](https://docs.alvys.com/en/api/reference/webhooks/trip-events.md): Reference for Alvys trip webhook events, including trip.status.changed and trip.changed, event payloads, and optional data.diff field-level changes.
- [Tender Events](https://docs.alvys.com/en/api/reference/webhooks/tender-events.md): Alvys tender webhook events including tender.created and tender.change.created, with payload envelope, change-type vocabulary, and subscription rules.
- [Change Diffs (data.diff)](https://docs.alvys.com/en/api/reference/webhooks/change-diffs.md): How load.changed and trip.changed webhook events expose changed fields via data.diff, including the optional previousAttributes payload for delta processing.

#### Webhook API

- [Create webhook subscription](https://docs.alvys.com/en/api/reference/webhooks/create-webhook-subscription.md): Creates a new webhook subscription. **Note:** You must verify the HMAC-SHA256 signature using the raw request body.
- [List webhooks](https://docs.alvys.com/en/api/reference/webhooks/list-webhooks.md): Returns paginated webhook subscriptions. Default size: 50. Ordered by creation date (newest first).
- [Get webhook](https://docs.alvys.com/en/api/reference/webhooks/get-webhook.md): Returns a specific webhook by ID
- [Update webhook](https://docs.alvys.com/en/api/reference/webhooks/update-webhook.md): Updates a webhook subscription. Supports RFC 7232 optimistic concurrency via `If-Match`.
- [Delete webhook](https://docs.alvys.com/en/api/reference/webhooks/delete-webhook.md): Soft-deletes a webhook subscription.Supports RFC 7232 optimistic concurrency via `If-Match`.
- [Enable webhook](https://docs.alvys.com/en/api/reference/webhooks/enable-webhook.md): Enables a disabled webhook subscription
- [Disable webhook](https://docs.alvys.com/en/api/reference/webhooks/disable-webhook.md): Disables a webhook subscription
- [Verify webhook ownership](https://docs.alvys.com/en/api/reference/webhooks/verify-webhook-ownership.md): Verifies webhook endpoint ownership using challenge-response mechanism
- [Test webhook delivery](https://docs.alvys.com/en/api/reference/webhooks/test-webhook-delivery.md): Sends a signed test payload to the configured URL to verify signature logic.
- [Get event types](https://docs.alvys.com/en/api/reference/webhooks/get-event-types.md): Returns all available webhook event types

#### Secrets

- [Reveal webhook secret](https://docs.alvys.com/en/api/reference/webhooks/reveal-webhook-secret.md): Decrypts and returns the webhook secret in plaintext
- [Rotate secret](https://docs.alvys.com/en/api/reference/webhooks/rotate-secret.md): Generates a new webhook secret while maintaining backward compatibility

#### Delivery Logs & Health

- [List delivery logs](https://docs.alvys.com/en/api/reference/webhooks/list-delivery-logs.md): Returns paginated delivery logs for a webhook with optional status, event type, and date range filters.
- [Get delivery log detail](https://docs.alvys.com/en/api/reference/webhooks/get-delivery-log-detail.md): Returns full detail of a single delivery attempt including response body and entity metadata.
- [Export delivery logs](https://docs.alvys.com/en/api/reference/webhooks/export-delivery-logs.md): Downloads delivery logs as CSV or JSON using the same filters as the list endpoint. Format resolution: (1) optional query parameter <c>Format=csv</c> or <c>Format=json</c> overrides everything when present; (2) otherwise the <c>Accept</c> header is used (<c>text/csv</c>, <c>application/csv</c>, <c>a…
- [Get webhook health metrics](https://docs.alvys.com/en/api/reference/webhooks/get-webhook-health-metrics.md): Returns aggregated delivery health metrics for a webhook over 1, 7, or 30 days.

### Changelog

- [Changelog](https://docs.alvys.com/en/api/changelog.md): Release notes and updates for the Alvys Public API, webhooks, MCP server, and integrations, with new entries added when surfaces change.

## OpenAPI Specs

- [alvys](/openapi/alvys.json)