Public API v1 — reference

Goal

Use a narrative reference for every shipped Public API v1 read endpoint.

Who it is for

Integrators implementing clients against AD-003 (read-only v1, scoped tokens, rate limits). No write endpoints.

Machine-readable spec

Download public-api-v1-openapi.yaml.

Base URL

{origin}/api/v1

Version uses the {version} route segment (v1). Deprecation headers may appear via api.version middleware.

Authentication

Requirement	Detail
Scheme	Authorization: Bearer {sanctum_token}
Tenant scope	Ability tenant:{uuid}
Resource scope	Additional api:* ability per group
CRM routes	Tenant must have crm module; else 422

Abilities (App\Integration\Api\ApiAbilities)

Ability	Routes
(tenant only)	GET /meta
api:parties.read	/parties, /parties/{party}
api:items.read	/items, /items/{item}
api:inventory.read	/inventory/availability
api:sales.read	/sales-invoices, /sales-invoices/{id}
api:purchases.read	/purchase-bills, /purchase-bills/{id}
api:crm.read	/crm/leads, /crm/opportunities (+ show)

Example token creation

$user->createToken('integration', [
    'tenant:'.$tenantId,
    'api:parties.read',
    'api:items.read',
])->plainTextToken;

Missing ability → 403.

Rate limiting

throttle:120,1 — 120 requests per minute per token/IP.

Tenant isolation

Tenant comes from the token — never from query/body. Operational data is RLS-scoped. Cross-tenant UUIDs → 404.

Pagination

Param	Default	Max
page	1	—
per_page	25	100

Laravel-style data / links / meta envelope.

Endpoints

GET /meta

Returns api_version and resolved tenant_id.

Parties (api:parties.read)

• GET /parties — active parties; optional ?q=
• GET /parties/{party} — archived → 404

Catalog (api:items.read)

• GET /items — active items; optional ?q=
• GET /items/{item}

Inventory (api:inventory.read)

• GET /inventory/availability?item_id={uuid}&warehouse_id={uuid?} — on_hand decimal string

Sales (api:sales.read)

• GET /sales-invoices — posted invoices and credit notes
• GET /sales-invoices/{id} — includes lines

Purchasing (api:purchases.read)

• GET /purchase-bills — posted bills and debit notes
• GET /purchase-bills/{id} — includes lines

CRM (api:crm.read + module)

• GET /crm/leads, GET /crm/leads/{id}
• GET /crm/opportunities, GET /crm/opportunities/{id}
• Module disabled → 422

Not in v1

Write APIs; staff /api/* SPA routes; /api/portal/*; POS internal routes; webhooks/connectors (integration module UI).

Related

• Public API v1 overview
• OpenAPI
• Integrator hub