OpenAPI JSONMarkdown Docs

OpenAPI Explorer

Automatycznie wygenerowana definicja OpenAPI dla wszystkich włączonych modułów.

Default server: https://demo.ex-rail.com

Dashboards

Showing 8 of 8 endpoints
GET/api/dashboards/layout
Auth requireddashboards.view

Load the current dashboard layout

Returns the saved widget layout together with the widgets the current user is allowed to place. Requires features: dashboards.view

Responses

200Current dashboard layout and available widgets.
Content-Type: application/json
{
  "layout": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "widgetId": "string",
        "order": 1
      }
    ]
  },
  "allowedWidgetIds": [
    "string"
  ],
  "canConfigure": true,
  "context": {
    "userId": "00000000-0000-4000-8000-000000000000",
    "tenantId": null,
    "organizationId": null,
    "userName": null,
    "userEmail": null,
    "userLabel": "string"
  },
  "widgets": [
    {
      "id": "string",
      "title": "string",
      "description": null,
      "defaultSize": "sm",
      "defaultEnabled": true,
      "defaultSettings": null,
      "features": [
        "string"
      ],
      "moduleId": "string",
      "icon": null,
      "loaderKey": "string",
      "supportsRefresh": true
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/dashboards/layout" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/dashboards/layout
Auth requireddashboards.configure

Persist dashboard layout changes

Saves the provided widget ordering, sizes, and settings for the current user. Requires features: dashboards.configure

Request body (application/json)

{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "widgetId": "string",
      "order": 1
    }
  ]
}

Responses

200Layout updated successfully.
Content-Type: application/json
{
  "ok": true
}
400Invalid layout payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/dashboards/layout" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"items\": [
    {
      \"id\": \"00000000-0000-4000-8000-000000000000\",
      \"widgetId\": \"string\",
      \"order\": 1
    }
  ]
}"
PATCH/api/dashboards/layout/{itemId}
Auth requireddashboards.configure

Update a dashboard layout item

Adjusts the size or settings for a single widget within the dashboard layout. Requires features: dashboards.configure

Parameters

NameInRequiredSchemaDescription
itemIdpathYesany

Request body (application/json)

{}

Responses

200Layout item updated.
Content-Type: application/json
{
  "ok": true
}
400Invalid payload or missing item id
Content-Type: application/json
{
  "error": "string"
}
404Item not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/dashboards/layout/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/dashboards/roles/widgets
Auth requireddashboards.admin.assign-widgets

Fetch widget assignments for a role

Returns the widgets explicitly assigned to the given role together with the evaluation scope. Requires features: dashboards.admin.assign-widgets

Parameters

NameInRequiredSchemaDescription
roleIdqueryYesany
tenantIdqueryNoany
organizationIdqueryNoany

Responses

200Current widget configuration for the role.
Content-Type: application/json
{
  "widgetIds": [
    "string"
  ],
  "hasCustom": true,
  "scope": {
    "tenantId": null,
    "organizationId": null
  }
}
400Missing role identifier
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/dashboards/roles/widgets?roleId=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/dashboards/roles/widgets
Auth requireddashboards.admin.assign-widgets

Update widgets assigned to a role

Persists the widget list for a role within the provided tenant and organization scope. Requires features: dashboards.admin.assign-widgets

Request body (application/json)

{
  "roleId": "00000000-0000-4000-8000-000000000000",
  "widgetIds": [
    "string"
  ]
}

Responses

200Widgets updated successfully.
Content-Type: application/json
{
  "ok": true,
  "widgetIds": [
    "string"
  ]
}
400Invalid payload or unknown widgets
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/dashboards/roles/widgets" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"roleId\": \"00000000-0000-4000-8000-000000000000\",
  \"widgetIds\": [
    \"string\"
  ]
}"
GET/api/dashboards/users/widgets
Auth requireddashboards.admin.assign-widgets

Read widget overrides for a user

Returns the widgets inherited and explicitly configured for the requested user within the current scope. Requires features: dashboards.admin.assign-widgets

Parameters

NameInRequiredSchemaDescription
userIdqueryYesany
tenantIdqueryNoany
organizationIdqueryNoany

Responses

200Widget settings for the user.
Content-Type: application/json
{
  "mode": "inherit",
  "widgetIds": [
    "string"
  ],
  "hasCustom": true,
  "effectiveWidgetIds": [
    "string"
  ],
  "scope": {
    "tenantId": null,
    "organizationId": null
  }
}
400Missing user identifier
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/dashboards/users/widgets?userId=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/dashboards/users/widgets
Auth requireddashboards.admin.assign-widgets

Update user-specific dashboard widgets

Sets the widget override mode and allowed widgets for a user. Passing `mode: inherit` clears overrides. Requires features: dashboards.admin.assign-widgets

Request body (application/json)

{
  "userId": "00000000-0000-4000-8000-000000000000",
  "mode": "inherit",
  "widgetIds": [
    "string"
  ]
}

Responses

200Overrides saved.
Content-Type: application/json
{
  "ok": true,
  "mode": "inherit",
  "widgetIds": [
    "string"
  ]
}
400Invalid payload or unknown widgets
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/dashboards/users/widgets" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"userId\": \"00000000-0000-4000-8000-000000000000\",
  \"mode\": \"inherit\",
  \"widgetIds\": [
    \"string\"
  ]
}"
POST/api/dashboards/widgets/data
Auth requiredanalytics.view

Fetch aggregated data for dashboard widgets

Executes an aggregation query against the specified entity type and returns the result. Supports date range filtering, grouping, and period-over-period comparison. Requires features: analytics.view

Request body (application/json)

{
  "entityType": "string",
  "metric": {
    "field": "string",
    "aggregate": "count"
  }
}

Responses

200Aggregated data for the widget.
Content-Type: application/json
{
  "value": null,
  "data": [
    {
      "value": null
    }
  ],
  "metadata": {
    "fetchedAt": "string",
    "recordCount": 1
  }
}
400Invalid request payload
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/dashboards/widgets/data" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"entityType\": \"string\",
  \"metric\": {
    \"field\": \"string\",
    \"aggregate\": \"count\"
  }
}"

Auth

Showing 3 of 3 endpoints
GET/api/auth/locale

GET /api/auth/locale

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/auth/locale" \
  -H "Accept: application/json"
POST/api/auth/locale

POST /api/auth/locale

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/auth/locale" \
  -H "Accept: application/json"
GET/api/auth/users/consents
Auth requiredauth.users.edit

List user consents

Returns all consent records for a given user, with integrity verification status. Requires features: auth.users.edit

Parameters

NameInRequiredSchemaDescription
userIdqueryYesany

Responses

200Consent list returned
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/auth/users/consents?userId=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Directory

Showing 9 of 9 endpoints
GET/api/directory/organization-switcher
Auth required

Load organization switcher menu

Returns the hierarchical menu of organizations the current user may switch to within the active tenant.

Responses

200Organization switcher payload.
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "depth": 1,
      "selectable": true,
      "children": []
    }
  ],
  "selectedId": null,
  "canManage": true,
  "canViewAllOrganizations": true,
  "tenantId": null,
  "tenants": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "isActive": true
    }
  ],
  "isSuperAdmin": true
}

Example

curl -X GET "https://api.open-mercato.local/api/directory/organization-switcher" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/directory/organizations
Auth requireddirectory.organizations.view

List organizations

Returns organizations using options, tree, or paginated manage view depending on the `view` parameter. Requires features: directory.organizations.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
viewqueryNoany
idsqueryNoany
tenantIdqueryNoany
includeInactivequeryNoany
statusqueryNoany

Responses

200Organization data for the requested view.
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "parentId": null,
      "parentName": null,
      "tenantId": null,
      "tenantName": null,
      "rootId": null,
      "treePath": null
    }
  ]
}
400Invalid query or tenant scope
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/directory/organizations?page=1&pageSize=50&view=options" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/directory/organizations
Auth requireddirectory.organizations.manage

Create organization

Creates a new organization within a tenant and optionally assigns hierarchy relationships. Requires features: directory.organizations.manage

Request body (application/json)

{
  "name": "string",
  "slug": null,
  "parentId": null
}

Responses

201Organization created.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/directory/organizations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"slug\": null,
  \"parentId\": null
}"
PUT/api/directory/organizations
Auth requireddirectory.organizations.manage

Update organization

Updates organization details and hierarchy assignments. Requires features: directory.organizations.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "slug": null,
  "parentId": null
}

Responses

200Organization updated.
Content-Type: application/json
{
  "ok": true
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/directory/organizations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"slug\": null,
  \"parentId\": null
}"
DELETE/api/directory/organizations
Auth requireddirectory.organizations.manage

Delete organization

Soft deletes an organization identified by id. Requires features: directory.organizations.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Organization deleted.
Content-Type: application/json
{
  "ok": true
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/directory/organizations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/directory/tenants
Auth requireddirectory.tenants.view

List tenants

Returns tenants visible to the current user with optional search and pagination. Requires features: directory.tenants.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
isActivequeryNoany

Responses

200Paged list of tenants.
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "isActive": true,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/directory/tenants?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/directory/tenants
Auth requireddirectory.tenants.manage

Create tenant

Creates a new tenant and returns its identifier. Requires features: directory.tenants.manage

Request body (application/json)

{
  "name": "string"
}

Responses

201Tenant created.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/directory/tenants" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\"
}"
PUT/api/directory/tenants
Auth requireddirectory.tenants.manage

Update tenant

Updates tenant properties such as name or activation state. Requires features: directory.tenants.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Tenant updated.
Content-Type: application/json
{
  "ok": true
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/directory/tenants" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/directory/tenants
Auth requireddirectory.tenants.manage

Delete tenant

Soft deletes the tenant identified by id. Requires features: directory.tenants.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Tenant removed.
Content-Type: application/json
{
  "ok": true
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/directory/tenants" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"

Customers

Showing 20 of 91 endpoints
GET/api/customers/activities
Auth requiredcustomers.activities.view

List activitys

Returns a paginated collection of activitys scoped to the authenticated organization. Requires features: customers.activities.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
entityIdqueryNoany
dealIdqueryNoany
activityTypequeryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated activitys
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "activityType": "string",
      "subject": null,
      "body": null,
      "occurredAt": null,
      "createdAt": "string",
      "appearanceIcon": null,
      "appearanceColor": null,
      "entityId": null,
      "authorUserId": null,
      "authorName": null,
      "authorEmail": null,
      "dealId": null,
      "dealTitle": null,
      "customValues": null,
      "activityTypeLabel": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/customers/activities?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/customers/activities
Auth requiredcustomers.activities.manage

Create activity

DEPRECATED (sunset 2026-06-30): Creates a timeline activity. Use POST /api/customers/interactions instead. Requires features: customers.activities.manage

Request body (application/json)

{
  "entityId": "00000000-0000-4000-8000-000000000000",
  "activityType": "string",
  "phoneNumber": null,
  "appearanceIcon": null,
  "appearanceColor": null
}

Responses

201Activity created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/customers/activities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"entityId\": \"00000000-0000-4000-8000-000000000000\",
  \"activityType\": \"string\",
  \"phoneNumber\": null,
  \"appearanceIcon\": null,
  \"appearanceColor\": null
}"
PUT/api/customers/activities
Auth requiredcustomers.activities.manage

Update activity

DEPRECATED (sunset 2026-06-30): Updates an activity. Use PUT /api/customers/interactions instead. Requires features: customers.activities.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "phoneNumber": null,
  "appearanceIcon": null,
  "appearanceColor": null
}

Responses

200Activity updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/customers/activities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"phoneNumber\": null,
  \"appearanceIcon\": null,
  \"appearanceColor\": null
}"
DELETE/api/customers/activities
Auth requiredcustomers.activities.manage

Delete activity

DEPRECATED (sunset 2026-06-30): Deletes an activity. Use DELETE /api/customers/interactions instead. Requires features: customers.activities.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Activity deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/customers/activities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/customers/addresses
Auth requiredcustomers.activities.view

List addresss

Returns a paginated collection of addresss scoped to the authenticated organization. Requires features: customers.activities.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
entityIdqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated addresss
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "entity_id": "00000000-0000-4000-8000-000000000000",
      "name": null,
      "purpose": null,
      "company_name": null,
      "address_line1": null,
      "address_line2": null,
      "building_number": null,
      "flat_number": null,
      "city": null,
      "region": null,
      "postal_code": null,
      "country": null,
      "latitude": null,
      "longitude": null,
      "is_primary": null,
      "organization_id": null,
      "tenant_id": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/customers/addresses?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/customers/addresses
Auth requiredcustomers.activities.manage

Create address

Creates a customer address record and associates it with the referenced entity. Requires features: customers.activities.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "entityId": "00000000-0000-4000-8000-000000000000",
  "addressLine1": "string"
}

Responses

201Address created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/customers/addresses" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"entityId\": \"00000000-0000-4000-8000-000000000000\",
  \"addressLine1\": \"string\"
}"
PUT/api/customers/addresses
Auth requiredcustomers.activities.manage

Update address

Updates fields on an existing customer address. Requires features: customers.activities.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Address updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/customers/addresses" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/customers/addresses
Auth requiredcustomers.activities.manage

Delete address

Deletes an address by id. The identifier may be included in the body or query. Requires features: customers.activities.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Address deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/customers/addresses" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/customers/assignable-staff
Auth requiredcustomers.roles.view

List staff members that can be assigned from customer flows

Returns active staff members linked to auth users. Access requires either customers.roles.manage or customers.activities.manage. Requires features: customers.roles.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany

Responses

200Assignable staff members
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamMemberId": "00000000-0000-4000-8000-000000000000",
      "userId": "00000000-0000-4000-8000-000000000000",
      "displayName": "string",
      "email": null,
      "teamName": null,
      "user": null,
      "team": null
    }
  ],
  "total": 1,
  "totalPages": 1
}
400Invalid request
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/customers/assignable-staff?page=1&pageSize=24" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/customers/comments
Auth requiredcustomers.activities.view

List comments

Returns a paginated collection of comments scoped to the authenticated organization. Requires features: customers.activities.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
entityIdqueryNoany
dealIdqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated comments
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "entity_id": null,
      "deal_id": null,
      "body": null,
      "author_user_id": null,
      "appearance_icon": null,
      "appearance_color": null,
      "organization_id": null,
      "tenant_id": null,
      "created_at": null,
      "updated_at": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/customers/comments?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/customers/comments
Auth requiredcustomers.activities.manage

Create comment

Adds a comment to a customer timeline. Requires features: customers.activities.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "entityId": "00000000-0000-4000-8000-000000000000",
  "body": "string",
  "appearanceIcon": null,
  "appearanceColor": null
}

Responses

201Comment created
Content-Type: application/json
{
  "id": null,
  "authorUserId": null
}

Example

curl -X POST "https://api.open-mercato.local/api/customers/comments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"entityId\": \"00000000-0000-4000-8000-000000000000\",
  \"body\": \"string\",
  \"appearanceIcon\": null,
  \"appearanceColor\": null
}"
PUT/api/customers/comments
Auth requiredcustomers.activities.manage

Update comment

Updates an existing timeline comment. Requires features: customers.activities.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "appearanceIcon": null,
  "appearanceColor": null
}

Responses

200Comment updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/customers/comments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"appearanceIcon\": null,
  \"appearanceColor\": null
}"
DELETE/api/customers/comments
Auth requiredcustomers.activities.manage

Delete comment

Deletes a comment identified by `id` supplied via body or query string. Requires features: customers.activities.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Comment deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/customers/comments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/customers/companies
Auth requiredcustomers.companies.view

List companies

Returns a paginated collection of companies scoped to the authenticated organization. Requires features: customers.companies.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
emailqueryNoany
emailStartsWithqueryNoany
emailContainsqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
statusqueryNoany
lifecycleStagequeryNoany
sourcequeryNoany
hasEmailqueryNoany
hasPhonequeryNoany
hasNextInteractionqueryNoany
createdFromqueryNoany
createdToqueryNoany
idqueryNoany
tagIdsqueryNoany
tagIdsEmptyqueryNoany
excludeIdsqueryNoany
excludeLinkedPersonIdqueryNoany
excludeLinkedCompanyIdqueryNoany
excludeLinkedDealIdqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated companies
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "description": null,
      "owner_user_id": null,
      "primary_email": null,
      "primary_phone": null,
      "status": null,
      "lifecycle_stage": null,
      "source": null,
      "next_interaction_at": null,
      "next_interaction_name": null,
      "next_interaction_ref_id": null,
      "next_interaction_icon": null,
      "next_interaction_color": null,
      "organization_id": null,
      "tenant_id": null,
      "created_at": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/customers/companies?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/customers/companies
Auth requiredcustomers.companies.manage

Create company

Creates a company record and associated profile data. Requires features: customers.companies.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "displayName": "string",
  "nextInteraction": null
}

Responses

201Company created
Content-Type: application/json
{
  "id": null,
  "companyId": null
}

Example

curl -X POST "https://api.open-mercato.local/api/customers/companies" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"displayName\": \"string\",
  \"nextInteraction\": null
}"
PUT/api/customers/companies
Auth requiredcustomers.companies.manage

Update company

Updates company profile fields, tags, or custom attributes. Requires features: customers.companies.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "nextInteraction": null
}

Responses

200Company updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/customers/companies" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"nextInteraction\": null
}"
DELETE/api/customers/companies
Auth requiredcustomers.companies.manage

Delete company

Deletes a company by id. The identifier can be provided via body or query. Requires features: customers.companies.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Company deleted
Content-Type: application/json
{
  "ok": true
}
422Company has dependent records (people, deals, or direct staff); unlink or reassign before delete.
Content-Type: application/json
{
  "error": "string",
  "code": "COMPANY_HAS_DEPENDENTS"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/customers/companies" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/customers/companies/{id}
Auth requiredcustomers.companies.view

Fetch company with related data

Returns a company customer record with optional related resources such as addresses, comments, activities, interactions, deals, todos, and linked people. Requires features: customers.companies.view

Parameters

NameInRequiredSchemaDescription
idpathYesany
includequeryNoanyComma-separated list of relations to include (addresses, comments, activities, interactions, deals, todos, people).

Responses

200Company detail payload
Content-Type: application/json
{
  "interactionMode": "canonical",
  "company": {
    "id": "00000000-0000-4000-8000-000000000000",
    "displayName": null,
    "description": null,
    "ownerUserId": null,
    "primaryEmail": null,
    "primaryPhone": null,
    "status": null,
    "lifecycleStage": null,
    "source": null,
    "nextInteractionAt": null,
    "nextInteractionName": null,
    "nextInteractionRefId": null,
    "nextInteractionIcon": null,
    "nextInteractionColor": null,
    "organizationId": null,
    "tenantId": null,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "profile": null,
  "customFields": {},
  "tags": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "label": "string",
      "color": null
    }
  ],
  "addresses": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": null,
      "purpose": null,
      "addressLine1": null,
      "addressLine2": null,
      "buildingNumber": null,
      "flatNumber": null,
      "city": null,
      "region": null,
      "postalCode": null,
      "country": null,
      "latitude": null,
      "longitude": null,
      "isPrimary": null,
      "createdAt": "string"
    }
  ],
  "comments": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "body": null,
      "authorUserId": null,
      "authorName": null,
      "authorEmail": null,
      "dealId": null,
      "createdAt": "string",
      "appearanceIcon": null,
      "appearanceColor": null
    }
  ],
  "activities": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "activityType": "string",
      "subject": null,
      "body": null,
      "occurredAt": null,
      "dealId": null,
      "authorUserId": null,
      "authorName": null,
      "authorEmail": null,
      "createdAt": "string",
      "appearanceIcon": null,
      "appearanceColor": null
    }
  ],
  "interactions": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "entityId": null,
      "interactionType": "string",
      "title": null,
      "body": null,
      "status": "string",
      "scheduledAt": null,
      "occurredAt": null,
      "priority": null,
      "authorUserId": null,
      "ownerUserId": null,
      "dealId": null,
      "organizationId": null,
      "tenantId": null,
      "authorName": null,
      "authorEmail": null,
      "dealTitle": null,
      "customValues": null,
      "appearanceIcon": null,
      "appearanceColor": null,
      "source": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "deals": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "title": null,
      "status": null,
      "pipelineStage": null,
      "valueAmount": null,
      "valueCurrency": null,
      "probability": null,
      "expectedCloseAt": null,
      "ownerUserId": null,
      "source": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "todos": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "todoId": "00000000-0000-4000-8000-000000000000",
      "todoSource": "string",
      "createdAt": "string",
      "createdByUserId": null,
      "title": null,
      "isDone": null,
      "priority": null,
      "severity": null,
      "description": null,
      "dueAt": null,
      "todoOrganizationId": null,
      "customValues": null
    }
  ],
  "people": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "displayName": null,
      "primaryEmail": null,
      "primaryPhone": null,
      "status": null,
      "lifecycleStage": null,
      "jobTitle": null,
      "department": null,
      "createdAt": "string",
      "organizationId": null,
      "source": null,
      "temperature": null,
      "linkedAt": null
    }
  ],
  "viewer": {
    "userId": null,
    "name": null,
    "email": null
  }
}
400Invalid identifier
Content-Type: application/json
{
  "error": "string"
}
404Company not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/customers/companies/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/customers/companies/{id}/people
Auth requiredcustomers.companies.view

List linked people for a company

Requires features: customers.companies.view

Parameters

NameInRequiredSchemaDescription
idpathYesany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
sortqueryNoany

Responses

200Paginated linked people
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "displayName": "string",
      "primaryEmail": null,
      "primaryPhone": null,
      "status": null,
      "lifecycleStage": null,
      "jobTitle": null,
      "department": null,
      "createdAt": "string",
      "organizationId": null,
      "temperature": null,
      "source": null,
      "linkedAt": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/customers/companies/:id/people?page=1&pageSize=20&sort=name-asc" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/customers/companies/{id}/roles
Auth requiredcustomers.roles.view

List roles for a company

Requires features: customers.roles.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Role assignments
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "entityType": "company",
      "entityId": "00000000-0000-4000-8000-000000000000",
      "userId": "00000000-0000-4000-8000-000000000000",
      "userName": null,
      "userEmail": null,
      "userPhone": null,
      "roleType": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
400Invalid request
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/customers/companies/00000000-0000-4000-8000-000000000000/roles" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Perspectives

Showing 4 of 4 endpoints
GET/api/perspectives/{tableId}
Auth requiredperspectives.use

Load perspectives for a table

Returns personal perspectives and available role defaults for the requested table identifier. Requires features: perspectives.use

Parameters

NameInRequiredSchemaDescription
tableIdpathYesany

Responses

200Current perspectives and defaults.
Content-Type: application/json
{
  "tableId": "string",
  "perspectives": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "tableId": "string",
      "settings": {},
      "isDefault": true,
      "createdAt": "string",
      "updatedAt": null
    }
  ],
  "defaultPerspectiveId": null,
  "rolePerspectives": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "tableId": "string",
      "settings": {},
      "isDefault": true,
      "createdAt": "string",
      "updatedAt": null,
      "roleId": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "roleName": null
    }
  ],
  "roles": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "hasPerspective": true,
      "hasDefault": true
    }
  ],
  "canApplyToRoles": true
}
400Invalid table identifier
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/perspectives/string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/perspectives/{tableId}
Auth requiredperspectives.use

Create or update a perspective

Saves a personal perspective and optionally applies the same configuration to selected roles. Requires features: perspectives.use

Parameters

NameInRequiredSchemaDescription
tableIdpathYesany

Request body (application/json)

{
  "name": "string",
  "settings": {}
}

Responses

200Perspective saved successfully.
Content-Type: application/json
{
  "perspective": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "tableId": "string",
    "settings": {},
    "isDefault": true,
    "createdAt": "string",
    "updatedAt": null
  },
  "rolePerspectives": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "tableId": "string",
      "settings": {},
      "isDefault": true,
      "createdAt": "string",
      "updatedAt": null,
      "roleId": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "roleName": null
    }
  ],
  "clearedRoleIds": [
    "00000000-0000-4000-8000-000000000000"
  ]
}
400Validation failed or invalid roles provided
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/perspectives/string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"settings\": {}
}"
DELETE/api/perspectives/{tableId}/{perspectiveId}
Auth requiredperspectives.use

Delete a personal perspective

Removes a perspective owned by the current user for the given table. Requires features: perspectives.use

Parameters

NameInRequiredSchemaDescription
tableIdpathYesany
perspectiveIdpathYesany

Responses

200Perspective removed.
Content-Type: application/json
{
  "success": true
}
400Invalid identifiers supplied
Content-Type: application/json
{
  "error": "string"
}
404Perspective not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/perspectives/string/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/perspectives/{tableId}/roles/{roleId}
Auth requiredperspectives.role_defaults

Clear role perspectives for a table

Removes all role-level perspectives associated with the provided role identifier for the table. Requires features: perspectives.role_defaults

Parameters

NameInRequiredSchemaDescription
tableIdpathYesany
roleIdpathYesany

Responses

200Role perspectives cleared.
Content-Type: application/json
{
  "success": true
}
400Invalid identifiers supplied
Content-Type: application/json
{
  "error": "string"
}
404Role not found in scope
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/perspectives/string/roles/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Configs

Showing 6 of 6 endpoints
GET/api/configs/cache
Auth requiredconfigs.cache.view

Get cache statistics

Returns detailed cache statistics including total entries and breakdown by cache segments. Requires cache service to be available. Requires features: configs.cache.view

Responses

200Cache statistics
Content-Type: application/json
{
  "total": 1,
  "segments": {
    "key": 1
  }
}
500Failed to resolve cache stats
Content-Type: application/json
{
  "error": "string"
}
503Cache service unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/configs/cache" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/configs/cache
Auth requiredconfigs.cache.manage

Purge cache

Purges cache entries. Supports two actions: purgeAll (clears entire cache) or purgeSegment (clears specific segment). Returns updated cache statistics after purge. Requires features: configs.cache.manage

Request body (application/json)

{
  "action": "purgeAll"
}

Responses

200Cache segment cleared successfully
Content-Type: application/json
{
  "action": "purgeSegment",
  "segment": "string",
  "deleted": 1,
  "stats": {
    "total": 1,
    "segments": {
      "key": 1
    }
  }
}
400Invalid request - missing segment identifier for purgeSegment action
Content-Type: application/json
{
  "error": "string"
}
500Failed to purge cache
Content-Type: application/json
{
  "error": "string"
}
503Cache service unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/configs/cache" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"action\": \"purgeAll\"
}"
GET/api/configs/system-status
Auth requiredconfigs.system_status.view

Get system health status

Returns comprehensive system health information including environment details, version, resource usage, and service connectivity status. Requires features: configs.system_status.view

Responses

200System status snapshot
Content-Type: application/json
{
  "generatedAt": "string",
  "runtimeMode": "development",
  "categories": [
    {
      "key": "profiling",
      "labelKey": "string",
      "descriptionKey": null,
      "items": [
        {
          "key": "string",
          "category": "profiling",
          "kind": "boolean",
          "labelKey": "string",
          "descriptionKey": "string",
          "docUrl": null,
          "defaultValue": null,
          "state": "enabled",
          "value": null,
          "normalizedValue": null
        }
      ]
    }
  ]
}
500Failed to load system status
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/configs/system-status" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/configs/system-status
Auth requiredconfigs.manage

Clear system cache

Purges the entire cache for the current tenant. Useful for troubleshooting or forcing fresh data loading. Requires features: configs.manage

Responses

200Cache cleared successfully
Content-Type: application/json
{
  "cleared": true
}
500Failed to purge cache
Content-Type: application/json
{
  "error": "string"
}
503Cache service unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/configs/system-status" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/configs/upgrade-actions
Auth requiredconfigs.manage

List pending upgrade actions

Returns a list of pending upgrade actions for the current version. These are one-time setup tasks that need to be executed after upgrading to a new version. Requires organization and tenant context. Requires features: configs.manage

Responses

200List of pending upgrade actions
Content-Type: application/json
{
  "version": "string",
  "actions": [
    {
      "id": "string",
      "version": "string",
      "message": "string",
      "ctaLabel": "string",
      "successMessage": "string",
      "loadingLabel": "string"
    }
  ]
}
400Missing organization or tenant context
Content-Type: application/json
{
  "error": "string"
}
500Failed to load upgrade actions
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/configs/upgrade-actions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/configs/upgrade-actions
Auth requiredconfigs.manage

Execute upgrade action

Executes a specific upgrade action by ID. Typically used for one-time setup tasks like seeding example data after version upgrade. Returns execution status and localized success message. Requires features: configs.manage

Request body (application/json)

{
  "actionId": "string"
}

Responses

200Upgrade action executed successfully
Content-Type: application/json
{
  "status": "string",
  "message": "string",
  "version": "string"
}
400Invalid request body or missing context
Content-Type: application/json
{
  "error": "string"
}
500Failed to execute upgrade action
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/configs/upgrade-actions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"actionId\": \"string\"
}"

Audit Logs

Showing 5 of 5 endpoints
GET/api/audit_logs/audit-logs/access
Auth requiredaudit_logs.view_self

Retrieve access logs

Fetches paginated access audit logs scoped to the authenticated user. Tenant administrators can optionally expand the search to other actors or organizations. Requires features: audit_logs.view_self

Parameters

NameInRequiredSchemaDescription
organizationIdqueryNoanyLimit results to a specific organization
actorUserIdqueryNoanyFilter by actor user id (tenant administrators only)
resourceKindqueryNoanyRestrict to a resource kind such as `order` or `product`
accessTypequeryNoanyAccess type filter, e.g. `read` or `export`
pagequeryNoanyPage number (default 1)
pageSizequeryNoanyPage size (default 50)
limitqueryNoanyExplicit maximum number of records when paginating manually
beforequeryNoanyReturn logs created before this ISO-8601 timestamp
afterqueryNoanyReturn logs created after this ISO-8601 timestamp

Responses

200Access logs returned successfully
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "resourceKind": "string",
      "resourceId": "string",
      "accessType": "string",
      "actorUserId": null,
      "actorUserName": null,
      "tenantId": null,
      "tenantName": null,
      "organizationId": null,
      "organizationName": null,
      "fields": [
        "string"
      ],
      "context": null,
      "createdAt": "string"
    }
  ],
  "canViewTenant": true,
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}
400Invalid filters supplied
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/audit_logs/audit-logs/access" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/audit_logs/audit-logs/actions
Auth requiredaudit_logs.view_self

Fetch action logs

Returns recent action audit log entries. Tenant administrators can widen the scope to other actors or organizations, and callers can optionally restrict results to undoable actions. Requires features: audit_logs.view_self

Parameters

NameInRequiredSchemaDescription
organizationIdqueryNoanyLimit results to a specific organization
actorUserIdqueryNoanyFilter logs created by specific actor IDs (tenant administrators only). Accepts a single UUID or a comma-separated UUID list.
resourceKindqueryNoanyFilter by resource kind (e.g., "order", "product")
resourceIdqueryNoanyFilter by resource ID (UUID of the specific record)
actionTypequeryNoanyFilter by action type (`create`, `edit`, `delete`, `assign`). Accepts a single value or a comma-separated list.
fieldNamequeryNoanyFilter to entries where the given field changed. Accepts a single field name or a comma-separated list.
includeRelatedqueryNoanyWhen `true`, also returns changes to child entities linked via parentResourceKind/parentResourceId
includeTotalqueryNoanyWhen `true`, the response includes the filtered total count.
undoableOnlyqueryNoanyWhen `true`, only undoable actions are returned
limitqueryNoanyMaximum number of records to return (default 50, max 1000)
offsetqueryNoanyZero-based record offset for pagination (legacy — prefer page/pageSize)
pagequeryNoanyPage number (default 1)
pageSizequeryNoanyPage size (default 50, max 200)
sortFieldqueryNoanySort field: `createdAt`, `user`, `action`, `field`, or `source`.
sortDirqueryNoanySort direction: `asc` or `desc`.
beforequeryNoanyReturn actions created before this ISO-8601 timestamp
afterqueryNoanyReturn actions created after this ISO-8601 timestamp

Responses

200Action logs retrieved successfully
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "commandId": "string",
      "actionLabel": null,
      "executionState": "done",
      "actorUserId": null,
      "actorUserName": null,
      "tenantId": null,
      "tenantName": null,
      "organizationId": null,
      "organizationName": null,
      "resourceKind": null,
      "resourceId": null,
      "parentResourceKind": null,
      "parentResourceId": null,
      "undoToken": null,
      "createdAt": "string",
      "updatedAt": "string",
      "snapshotBefore": null,
      "snapshotAfter": null,
      "changes": null,
      "context": null
    }
  ],
  "canViewTenant": true,
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}
400Invalid filter values
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/audit_logs/audit-logs/actions?includeRelated=false&includeTotal=false&undoableOnly=false" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/audit_logs/audit-logs/actions/export
Auth requiredaudit_logs.view_self

Export action logs as CSV

Returns a CSV attachment containing filtered action audit log entries. Tenant administrators can widen the scope to other actors or organizations. Requires features: audit_logs.view_self

Parameters

NameInRequiredSchemaDescription
organizationIdqueryNoanyLimit results to a specific organization
actorUserIdqueryNoanyFilter logs created by specific actor IDs (tenant administrators only). Accepts a single UUID or a comma-separated UUID list.
resourceKindqueryNoanyFilter by resource kind (e.g., "order", "product")
resourceIdqueryNoanyFilter by resource ID (UUID of the specific record)
actionTypequeryNoanyFilter by action type (`create`, `edit`, `delete`, `assign`). Accepts a single value or a comma-separated list.
fieldNamequeryNoanyFilter to entries where the given field changed. Accepts a single field name or a comma-separated list.
includeRelatedqueryNoanyWhen `true`, also returns changes to child entities linked via parentResourceKind/parentResourceId
undoableOnlyqueryNoanyWhen `true`, only undoable actions are returned
limitqueryNoanyMaximum number of records to export (default 1000, capped at 1000)
sortFieldqueryNoanySort field: `createdAt`, `user`, `action`, `field`, or `source`.
sortDirqueryNoanySort direction: `asc` or `desc`.
beforequeryNoanyReturn actions created before this ISO-8601 timestamp
afterqueryNoanyReturn actions created after this ISO-8601 timestamp

Responses

200CSV export generated successfully
Content-Type: application/json
{
  "file": "csv"
}
400Invalid filter values
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/audit_logs/audit-logs/actions/export?includeRelated=false&undoableOnly=false" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/audit_logs/audit-logs/actions/redo
Auth requiredaudit_logs.redo_self

Redo by action log id

Redoes the latest undone command owned by the caller. Requires the action to still be eligible for redo within tenant and organization scope. Requires features: audit_logs.redo_self

Request body (application/json)

{
  "logId": "string"
}

Responses

200Redo executed successfully
Content-Type: application/json
{
  "ok": true,
  "logId": null,
  "undoToken": null
}
400Log not eligible for redo
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/audit_logs/audit-logs/actions/redo" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"logId\": \"string\"
}"
POST/api/audit_logs/audit-logs/actions/undo
Auth requiredaudit_logs.undo_self

Undo action by token

Replays the undo handler registered for a command. The provided undo token must match the latest undoable log entry accessible to the caller. Requires features: audit_logs.undo_self

Request body (application/json)

{
  "undoToken": "string"
}

Responses

200Undo applied successfully
Content-Type: application/json
{
  "ok": true,
  "logId": "string"
}
400Invalid or unavailable undo token
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/audit_logs/audit-logs/actions/undo" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"undoToken\": \"string\"
}"

Attachments

Showing 14 of 14 endpoints
GET/api/attachments
Auth requiredattachments.view

List attachments for a record

Returns uploaded attachments for the given entity record, ordered by newest first. Requires features: attachments.view

Parameters

NameInRequiredSchemaDescription
entityIdqueryYesanyEntity identifier that owns the attachments
recordIdqueryYesanyRecord identifier within the entity
pagequeryNoany
pageSizequeryNoany

Responses

200Attachments found for the record
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "url": "string",
      "fileName": "string",
      "fileSize": 1,
      "createdAt": "string",
      "mimeType": null,
      "content": null
    }
  ]
}
400Missing entity or record identifiers
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/attachments?entityId=string&recordId=string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/attachments
Auth requiredattachments.manage

Upload attachment

Uploads a new attachment using multipart form-data and stores metadata for later retrieval. Requires features: attachments.manage

Request body (multipart/form-data)

entityId=string
recordId=string
file=string

Responses

200Attachment stored successfully
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "url": "string",
    "fileName": "string",
    "fileSize": 1,
    "content": null
  }
}
400Payload validation error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/attachments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -d "{
  \"entityId\": \"string\",
  \"recordId\": \"string\",
  \"file\": \"string\"
}"
DELETE/api/attachments
Auth requiredattachments.manage

Delete attachment

Removes an uploaded attachment and deletes the stored asset. Requires features: attachments.manage

Parameters

NameInRequiredSchemaDescription
idqueryYesany

Responses

200Attachment deleted
Content-Type: application/json
{
  "ok": true
}
400Missing attachment identifier
Content-Type: application/json
{
  "error": "string"
}
404Attachment not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/attachments?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/attachments/file/{id}

Download or serve attachment file

Returns the raw file content for an attachment. Path parameter: {id} - Attachment UUID. Query parameter: ?download=1 - Force file download with Content-Disposition header. Access control is enforced based on partition settings.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200File content with appropriate MIME type
Content-Type: application/json
"string"
400Missing attachment ID
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized - authentication required for private partitions
Content-Type: application/json
{
  "error": "string"
}
403Forbidden - insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
404Attachment or file not found
Content-Type: application/json
{
  "error": "string"
}
500Partition misconfigured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/attachments/file/:id" \
  -H "Accept: application/json"
GET/api/attachments/image/{id}/{slug}

Serve image with optional resizing

Returns an image attachment with optional on-the-fly resizing and cropping. Resized images are cached for performance. Only works with image MIME types. Path parameter: {id} - Attachment UUID. Query parameters: ?width=N (1-4000 pixels), ?height=N (1-4000 pixels), ?cropType=cover|contain (resize behavior).

Parameters

NameInRequiredSchemaDescription
idpathYesany
slugpathNoany

Responses

200Binary image content (Content-Type: image/jpeg, image/png, etc.)
Content-Type: application/json
"string"
400Invalid parameters, missing ID, or non-image attachment
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized - authentication required for private partitions
Content-Type: application/json
{
  "error": "string"
}
403Forbidden - insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
404Image not found
Content-Type: application/json
{
  "error": "string"
}
500Partition misconfigured or image rendering failed
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/attachments/image/:id/:slug" \
  -H "Accept: application/json"
GET/api/attachments/library
Auth requiredattachments.view

List attachments

Returns paginated list of attachments with optional filtering by search term, partition, and tags. Includes available tags and partitions. Requires features: attachments.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoanyPage number for pagination
pageSizequeryNoanyNumber of items per page (max 100)
searchqueryNoanySearch by file name (case-insensitive)
partitionqueryNoanyFilter by partition code
tagsqueryNoanyFilter by tags (comma-separated)
sortFieldqueryNoanyField to sort by
sortDirqueryNoanySort direction

Responses

200Attachments list with pagination and metadata
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "fileName": "string",
      "fileSize": 1,
      "mimeType": "string",
      "partitionCode": "string",
      "partitionTitle": null,
      "url": null,
      "createdAt": "string",
      "tags": [
        "string"
      ],
      "assignments": [],
      "content": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1,
  "availableTags": [
    "string"
  ],
  "partitions": [
    {
      "code": "string",
      "title": "string",
      "description": null,
      "isPublic": true
    }
  ]
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/attachments/library?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/attachments/library/{id}
Auth requiredattachments.view

Get attachment details

Returns complete details of an attachment including metadata, tags, assignments, and custom fields. Requires features: attachments.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Attachment details
Content-Type: application/json
{
  "item": {
    "id": "00000000-0000-4000-8000-000000000000",
    "fileName": "string",
    "fileSize": 1,
    "mimeType": "string",
    "partitionCode": "string",
    "partitionTitle": null,
    "tags": [
      "string"
    ],
    "assignments": [],
    "content": null,
    "customFields": null
  }
}
400Invalid attachment ID
Content-Type: application/json
{
  "error": "string"
}
404Attachment not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/attachments/library/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/attachments/library/{id}
Auth requiredattachments.manage

Update attachment metadata

Updates attachment tags, assignments, and custom fields. Emits CRUD side effects for indexing and events. Requires features: attachments.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

200Attachment updated successfully
Content-Type: application/json
{
  "ok": true
}
400Invalid payload or attachment ID
Content-Type: application/json
{
  "error": "string"
}
404Attachment not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to save attributes
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/attachments/library/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
DELETE/api/attachments/library/{id}
Auth requiredattachments.manage

Delete attachment

Permanently deletes an attachment file from storage and database. Emits CRUD side effects. Requires features: attachments.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Attachment deleted successfully
Content-Type: application/json
{
  "ok": true
}
400Invalid attachment ID
Content-Type: application/json
{
  "error": "string"
}
404Attachment not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/attachments/library/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/attachments/partitions
Auth requiredattachments.manage

List all attachment partitions

Returns all configured attachment partitions with storage settings, OCR configuration, and access control settings. Requires features: attachments.manage

Responses

200List of partitions
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "code": "string",
      "title": "string",
      "description": null,
      "isPublic": true,
      "requiresOcr": true,
      "ocrModel": null,
      "createdAt": null,
      "updatedAt": null,
      "envKey": "string"
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/attachments/partitions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/attachments/partitions
Auth requiredattachments.manage

Create new partition

Creates a new attachment partition with specified storage and OCR settings. Requires unique partition code. Requires features: attachments.manage

Request body (application/json)

{
  "code": "string",
  "title": "string",
  "description": null,
  "ocrModel": null
}

Responses

201Partition created successfully
Content-Type: application/json
{
  "item": {
    "id": "00000000-0000-4000-8000-000000000000",
    "code": "string",
    "title": "string",
    "description": null,
    "isPublic": true,
    "requiresOcr": true,
    "ocrModel": null,
    "createdAt": null,
    "updatedAt": null,
    "envKey": "string"
  }
}
400Invalid payload or partition code
Content-Type: application/json
{
  "error": "string"
}
409Partition code already exists
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/attachments/partitions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"code\": \"string\",
  \"title\": \"string\",
  \"description\": null,
  \"ocrModel\": null
}"
PUT/api/attachments/partitions
Auth requiredattachments.manage

Update partition

Updates an existing partition. Partition code cannot be changed. Title, description, OCR settings, and access control can be modified. Requires features: attachments.manage

Request body (application/json)

{
  "code": "string",
  "title": "string",
  "description": null,
  "ocrModel": null,
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Partition updated successfully
Content-Type: application/json
{
  "item": {
    "id": "00000000-0000-4000-8000-000000000000",
    "code": "string",
    "title": "string",
    "description": null,
    "isPublic": true,
    "requiresOcr": true,
    "ocrModel": null,
    "createdAt": null,
    "updatedAt": null,
    "envKey": "string"
  }
}
400Invalid payload or code change attempt
Content-Type: application/json
{
  "error": "string"
}
404Partition not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/attachments/partitions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"code\": \"string\",
  \"title\": \"string\",
  \"description\": null,
  \"ocrModel\": null,
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/attachments/partitions
Auth requiredattachments.manage

Delete partition

Deletes a partition. Default partitions cannot be deleted. Partitions with existing attachments cannot be deleted. Requires features: attachments.manage

Responses

200Partition deleted successfully
Content-Type: application/json
{
  "ok": true
}
400Invalid ID or default partition deletion attempt
Content-Type: application/json
{
  "error": "string"
}
404Partition not found
Content-Type: application/json
{
  "error": "string"
}
409Partition in use
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/attachments/partitions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/attachments/transfer
Auth requiredattachments.manage

Transfer attachments to different record

Transfers one or more attachments from one record to another within the same entity type. Updates attachment assignments and metadata to reflect the new record. Requires features: attachments.manage

Request body (application/json)

{
  "entityId": "string",
  "attachmentIds": [
    "00000000-0000-4000-8000-000000000000"
  ],
  "toRecordId": "string"
}

Responses

200Attachments transferred successfully
Content-Type: application/json
{
  "ok": true,
  "updated": 1
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Attachments not found
Content-Type: application/json
{
  "error": "string"
}
500Attachment model missing
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/attachments/transfer" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"entityId\": \"string\",
  \"attachmentIds\": [
    \"00000000-0000-4000-8000-000000000000\"
  ],
  \"toRecordId\": \"string\"
}"

Catalog

Showing 20 of 36 endpoints
POST/api/catalog/bulk-delete
Auth requiredcatalog.products.manage

Start bulk deleting catalog products

Requires features: catalog.products.manage

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/catalog/bulk-delete" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/catalog/categories
Auth requiredcatalog.categories.view

List categories

Returns a paginated collection of categories scoped to the authenticated organization. Requires features: catalog.categories.view

Parameters

NameInRequiredSchemaDescription
viewqueryNoany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
statusqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated categories
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "slug": null,
      "description": null,
      "parentId": null,
      "parentName": null,
      "depth": 1,
      "treePath": "string",
      "pathLabel": "string",
      "childCount": 1,
      "descendantCount": 1,
      "isActive": true,
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "tenantId": "00000000-0000-4000-8000-000000000000"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/catalog/categories?view=manage&page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/catalog/categories
Auth requiredcatalog.categories.manage

Create category

Creates a new product category. Requires features: catalog.categories.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "slug": null,
  "parentId": null
}

Responses

201Category created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/catalog/categories" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"name\": \"string\",
  \"slug\": null,
  \"parentId\": null
}"
PUT/api/catalog/categories
Auth requiredcatalog.categories.manage

Update category

Updates an existing category by id. Requires features: catalog.categories.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "slug": null,
  "parentId": null
}

Responses

200Category updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/catalog/categories" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"slug\": null,
  \"parentId\": null
}"
DELETE/api/catalog/categories
Auth requiredcatalog.categories.manage

Delete category

Deletes a category by id. Requires features: catalog.categories.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Category deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/catalog/categories" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/catalog/dictionaries/{key}
Auth requiredcatalog.products.manage

Get dictionary entries by key

Returns dictionary entries for a specific key (e.g., currency, unit). Requires features: catalog.products.manage

Parameters

NameInRequiredSchemaDescription
keypathYesany

Responses

200Dictionary entries
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "entries": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "value": "string",
      "label": "string",
      "color": null,
      "icon": null
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/catalog/dictionaries/:key" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/catalog/offers
Auth requiredsales.channels.manage

List offers

Returns a paginated collection of offers scoped to the authenticated organization. Requires features: sales.channels.manage

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
productIdqueryNoany
channelIdqueryNoany
channelIdsqueryNoany
idqueryNoany
searchqueryNoany
isActivequeryNoany
withDeletedqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated offers
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "productId": null,
      "organizationId": null,
      "tenantId": null,
      "channelId": null,
      "title": "string",
      "description": null,
      "defaultMediaId": null,
      "defaultMediaUrl": null,
      "metadata": null,
      "isActive": null,
      "createdAt": null,
      "updatedAt": null,
      "product": null,
      "productChannelPrice": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/catalog/offers?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/catalog/offers
Auth requiredsales.channels.manage

Create offer

Creates a new offer linking a product to a sales channel. Requires features: sales.channels.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "channelId": "00000000-0000-4000-8000-000000000000",
  "title": "string",
  "defaultMediaId": null,
  "defaultMediaUrl": null,
  "productId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Offer created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/catalog/offers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"channelId\": \"00000000-0000-4000-8000-000000000000\",
  \"title\": \"string\",
  \"defaultMediaId\": null,
  \"defaultMediaUrl\": null,
  \"productId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/catalog/offers
Auth requiredsales.channels.manage

Update offer

Updates an existing offer by id. Requires features: sales.channels.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "defaultMediaId": null,
  "defaultMediaUrl": null
}

Responses

200Offer updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/catalog/offers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"defaultMediaId\": null,
  \"defaultMediaUrl\": null
}"
DELETE/api/catalog/offers
Auth requiredsales.channels.manage

Delete offer

Deletes an offer by id. Requires features: sales.channels.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Offer deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/catalog/offers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/catalog/option-schemas
Auth requiredcatalog.products.view

List option schemas

Returns a paginated collection of option schemas scoped to the authenticated organization. Requires features: catalog.products.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
idqueryNoany
searchqueryNoany
isActivequeryNoany
withDeletedqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated option schemas
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "code": null,
      "description": null,
      "schema": null,
      "metadata": null,
      "is_active": null,
      "created_at": null,
      "updated_at": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/catalog/option-schemas?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/catalog/option-schemas
Auth requiredcatalog.settings.manage

Create option schema

Creates a new option schema template for product configurations. Requires features: catalog.settings.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "schema": {
    "options": [
      {
        "code": "string",
        "label": "string",
        "inputType": "select"
      }
    ]
  }
}

Responses

201Option Schema created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/catalog/option-schemas" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"name\": \"string\",
  \"schema\": {
    \"options\": [
      {
        \"code\": \"string\",
        \"label\": \"string\",
        \"inputType\": \"select\"
      }
    ]
  }
}"
PUT/api/catalog/option-schemas
Auth requiredcatalog.settings.manage

Update option schema

Updates an existing option schema by id. Requires features: catalog.settings.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Option Schema updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/catalog/option-schemas" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/catalog/option-schemas
Auth requiredcatalog.settings.manage

Delete option schema

Deletes an option schema by id. Requires features: catalog.settings.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Option Schema deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/catalog/option-schemas" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/catalog/price-kinds
Auth requiredcatalog.settings.manage

List price kinds

Returns a paginated collection of price kinds scoped to the authenticated organization. Requires features: catalog.settings.manage

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
isPromotionqueryNoany
isActivequeryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated price kinds
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "organization_id": null,
      "tenant_id": null,
      "code": "string",
      "title": "string",
      "display_mode": null,
      "currency_code": null,
      "is_promotion": null,
      "is_active": null,
      "created_at": null,
      "updated_at": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/catalog/price-kinds?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/catalog/price-kinds
Auth requiredcatalog.settings.manage

Create price kind

Creates a new price kind for categorizing product prices. Requires features: catalog.settings.manage

Request body (application/json)

{
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "code": "string",
  "title": "string",
  "displayMode": "excluding-tax"
}

Responses

201Price Kind created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/catalog/price-kinds" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"code\": \"string\",
  \"title\": \"string\",
  \"displayMode\": \"excluding-tax\"
}"
PUT/api/catalog/price-kinds
Auth requiredcatalog.settings.manage

Update price kind

Updates an existing price kind by id. Requires features: catalog.settings.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "displayMode": "excluding-tax"
}

Responses

200Price Kind updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/catalog/price-kinds" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"displayMode\": \"excluding-tax\"
}"
DELETE/api/catalog/price-kinds
Auth requiredcatalog.settings.manage

Delete price kind

Deletes a price kind by id. Requires features: catalog.settings.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Price Kind deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/catalog/price-kinds" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/catalog/prices
Auth requiredcatalog.products.view

List prices

Returns a paginated collection of prices scoped to the authenticated organization. Requires features: catalog.products.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
productIdqueryNoany
variantIdqueryNoany
offerIdqueryNoany
channelIdqueryNoany
currencyCodequeryNoany
priceKindIdqueryNoany
kindqueryNoany
userIdqueryNoany
userGroupIdqueryNoany
customerIdqueryNoany
customerGroupIdqueryNoany
quantityqueryNoany
quantityUnitqueryNoany
withDeletedqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated prices
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "product_id": null,
      "variant_id": null,
      "offer_id": null,
      "currency_code": null,
      "price_kind_id": null,
      "kind": null,
      "min_quantity": null,
      "max_quantity": null,
      "unit_price_net": null,
      "unit_price_gross": null,
      "tax_rate": null,
      "tax_amount": null,
      "channel_id": null,
      "user_id": null,
      "user_group_id": null,
      "customer_id": null,
      "customer_group_id": null,
      "metadata": null,
      "starts_at": null,
      "ends_at": null,
      "created_at": null,
      "updated_at": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/catalog/prices?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/catalog/prices
Auth requiredcatalog.pricing.manage

Create price

Creates a new price entry for a product or variant. Requires features: catalog.pricing.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "currencyCode": "string",
  "priceKindId": "00000000-0000-4000-8000-000000000000",
  "taxRateId": null
}

Responses

201Price created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/catalog/prices" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"currencyCode\": \"string\",
  \"priceKindId\": \"00000000-0000-4000-8000-000000000000\",
  \"taxRateId\": null
}"

Sales

Showing 20 of 108 endpoints
GET/api/sales/adjustment-kinds
Auth requiredsales.orders.view

List sales adjustment kinds

Returns a paginated collection of sales adjustment kinds that belong to the current organization. Requires features: sales.orders.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated sales adjustment kinds
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "value": "string",
      "label": null,
      "color": null,
      "icon": null,
      "organizationId": null,
      "tenantId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/sales/adjustment-kinds?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/sales/adjustment-kinds
Auth requiredsales.settings.manage

Create sales adjustment kind

Creates an adjustment kind. Requires features: sales.settings.manage

Request body (application/json)

{}

Responses

201Sales adjustment kind created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/sales/adjustment-kinds" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
PUT/api/sales/adjustment-kinds
Auth requiredsales.settings.manage

Update sales adjustment kind

Updates an adjustment kind. Requires features: sales.settings.manage

Request body (application/json)

{}

Responses

200Sales adjustment kind updated
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X PUT "https://api.open-mercato.local/api/sales/adjustment-kinds" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
DELETE/api/sales/adjustment-kinds
Auth requiredsales.settings.manage

Delete sales adjustment kind

Deletes an adjustment kind. Requires features: sales.settings.manage

Request body (application/json)

{}

Responses

200Sales adjustment kind deleted
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/sales/adjustment-kinds" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/sales/channels
Auth requiredsales.channels.manage

List sales channels

Manage sales channels to segment orders and pricing across marketplaces or stores. Requires features: sales.channels.manage

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
isActivequeryNoany
sortFieldqueryNoany
sortDirqueryNoany
withDeletedqueryNoany

Responses

200Paginated sales channels
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "code": null,
      "description": null,
      "statusEntryId": null,
      "isActive": true,
      "organizationId": null,
      "tenantId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/sales/channels?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/sales/channels
Auth requiredsales.channels.manage

Create sales channel

Creates a new sales channel. Requires features: sales.channels.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "code": "string"
}

Responses

201Sales channel created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/sales/channels" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"name\": \"string\",
  \"code\": \"string\"
}"
PUT/api/sales/channels
Auth requiredsales.channels.manage

Update sales channel

Updates an existing sales channel by id. Requires features: sales.channels.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "code": "string"
}

Responses

200Sales channel updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/sales/channels" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"code\": \"string\"
}"
DELETE/api/sales/channels
Auth requiredsales.channels.manage

Delete sales channel

Deletes a sales channel identified by id. Requires features: sales.channels.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Sales channel deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/sales/channels" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/sales/credit-memos
Auth requiredsales.credit_memos.manage

List creditmemos

Returns a paginated collection of creditmemos that belong to the current organization. Requires features: sales.credit_memos.manage

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idqueryNoany
orderIdqueryNoany
invoiceIdqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated creditmemos
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "creditMemoNumber": "string",
      "status": null,
      "reason": null,
      "issueDate": null,
      "currencyCode": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/sales/credit-memos?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/sales/credit-memos
Auth requiredsales.credit_memos.manage

Create creditmemo

Create a new credit memo Requires features: sales.credit_memos.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "currencyCode": "string"
}

Responses

201CreditMemo created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/sales/credit-memos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"currencyCode\": \"string\"
}"
PUT/api/sales/credit-memos
Auth requiredsales.credit_memos.manage

Update creditmemo

Update a credit memo Requires features: sales.credit_memos.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200CreditMemo updated
Content-Type: application/json
{
  "creditMemoId": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X PUT "https://api.open-mercato.local/api/sales/credit-memos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/sales/credit-memos
Auth requiredsales.credit_memos.manage

Delete creditmemo

Delete a credit memo Requires features: sales.credit_memos.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200CreditMemo deleted
Content-Type: application/json
{
  "creditMemoId": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/sales/credit-memos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/sales/dashboard/widgets/new-orders
Auth requireddashboards.viewsales.widgets.new-orders

Fetch recently created sales orders

Fetches recently created sales orders for the dashboard widget with a configurable date period. Requires features: dashboards.view, sales.widgets.new-orders

Parameters

NameInRequiredSchemaDescription
limitqueryNoany
datePeriodqueryNoany
customFromqueryNoany
customToqueryNoany
tenantIdqueryNoany
organizationIdqueryNoany

Responses

200List of recent orders
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "orderNumber": "string",
      "status": null,
      "fulfillmentStatus": null,
      "paymentStatus": null,
      "customerName": null,
      "customerEntityId": null,
      "netAmount": "string",
      "grossAmount": "string",
      "currency": null,
      "createdAt": "string"
    }
  ],
  "total": 1,
  "dateRange": {
    "from": "string",
    "to": "string"
  }
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}
500Widget failed to load
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/sales/dashboard/widgets/new-orders?limit=5&datePeriod=last24h" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/sales/dashboard/widgets/new-quotes
Auth requireddashboards.viewsales.widgets.new-quotes

Fetch recently created sales quotes

Fetches recently created sales quotes for the dashboard widget with a configurable date period. Requires features: dashboards.view, sales.widgets.new-quotes

Parameters

NameInRequiredSchemaDescription
limitqueryNoany
datePeriodqueryNoany
customFromqueryNoany
customToqueryNoany
tenantIdqueryNoany
organizationIdqueryNoany

Responses

200List of recent quotes
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "quoteNumber": "string",
      "status": null,
      "customerName": null,
      "customerEntityId": null,
      "validFrom": null,
      "validUntil": null,
      "netAmount": "string",
      "grossAmount": "string",
      "currency": null,
      "createdAt": "string",
      "convertedOrderId": null
    }
  ],
  "total": 1,
  "dateRange": {
    "from": "string",
    "to": "string"
  }
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}
500Widget failed to load
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/sales/dashboard/widgets/new-quotes?limit=5&datePeriod=last24h" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/sales/delivery-windows
Auth requiredsales.settings.manage

List delivery windows

Define delivery windows to communicate lead times and cut-off rules for sales orders. Requires features: sales.settings.manage

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
isActivequeryNoany
sortFieldqueryNoany
sortDirqueryNoany
withDeletedqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated delivery windows
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "code": null,
      "description": null,
      "leadTimeDays": null,
      "cutoffTime": null,
      "timezone": null,
      "isActive": true,
      "metadata": null,
      "organizationId": null,
      "tenantId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/sales/delivery-windows?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/sales/delivery-windows
Auth requiredsales.settings.manage

Create delivery window

Creates a new delivery window. Requires features: sales.settings.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "code": "string"
}

Responses

201Delivery window created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/sales/delivery-windows" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"name\": \"string\",
  \"code\": \"string\"
}"
PUT/api/sales/delivery-windows
Auth requiredsales.settings.manage

Update delivery window

Updates an existing delivery window by id. Requires features: sales.settings.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Delivery window updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/sales/delivery-windows" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/sales/delivery-windows
Auth requiredsales.settings.manage

Delete delivery window

Deletes a delivery window identified by id. Requires features: sales.settings.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Delivery window deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/sales/delivery-windows" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/sales/document-addresses
Auth required

List document addresss

Returns a paginated collection of document addresss that belong to the current organization.

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
documentIdqueryYesany
documentKindqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated document addresss
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "document_id": "00000000-0000-4000-8000-000000000000",
      "document_kind": "order",
      "customer_address_id": null,
      "name": null,
      "purpose": null,
      "company_name": null,
      "address_line1": "string",
      "address_line2": null,
      "building_number": null,
      "flat_number": null,
      "city": null,
      "region": null,
      "postal_code": null,
      "country": null,
      "latitude": null,
      "longitude": null,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/sales/document-addresses?page=1&pageSize=50&documentId=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/sales/document-addresses
Auth required

Create document address

Creates a sales document address linked to an order or quote.

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "documentId": "00000000-0000-4000-8000-000000000000",
  "documentKind": "order",
  "name": null,
  "purpose": null,
  "companyName": null,
  "addressLine1": "string",
  "addressLine2": null,
  "city": null,
  "region": null,
  "postalCode": null,
  "country": null,
  "buildingNumber": null,
  "flatNumber": null,
  "latitude": null,
  "longitude": null
}

Responses

201Document address created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/sales/document-addresses" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"documentId\": \"00000000-0000-4000-8000-000000000000\",
  \"documentKind\": \"order\",
  \"name\": null,
  \"purpose\": null,
  \"companyName\": null,
  \"addressLine1\": \"string\",
  \"addressLine2\": null,
  \"city\": null,
  \"region\": null,
  \"postalCode\": null,
  \"country\": null,
  \"buildingNumber\": null,
  \"flatNumber\": null,
  \"latitude\": null,
  \"longitude\": null
}"

Api Keys

Showing 3 of 3 endpoints
GET/api/api_keys/keys
Auth requiredapi_keys.view

List API keys

Returns paginated API keys visible to the current user, including per-key role assignments and organization context. Requires features: api_keys.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany

Responses

200Collection of API keys
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "description": null,
      "keyPrefix": "string",
      "organizationId": null,
      "organizationName": null,
      "createdAt": "string",
      "lastUsedAt": null,
      "expiresAt": null,
      "roles": [
        {
          "id": "string",
          "name": null
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}
400Tenant context missing
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/api_keys/keys" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/api_keys/keys
Auth requiredapi_keys.create

Create API key

Creates a new API key, returning the one-time secret value together with the generated key prefix and scope details. Requires features: api_keys.create

Request body (application/json)

{
  "name": "string",
  "description": null,
  "tenantId": null,
  "organizationId": null,
  "roles": [],
  "expiresAt": null
}

Responses

201API key created successfully
Content-Type: application/json
{
  "id": "string",
  "name": "string",
  "keyPrefix": "string",
  "tenantId": null,
  "organizationId": null,
  "roles": [
    {
      "id": "string",
      "name": null
    }
  ]
}
400Invalid payload or missing tenant context
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/api_keys/keys" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"description\": null,
  \"tenantId\": null,
  \"organizationId\": null,
  \"roles\": [],
  \"expiresAt\": null
}"
DELETE/api/api_keys/keys
Auth requiredapi_keys.delete

Delete API key

Removes an API key by identifier. The key must belong to the current tenant and fall within the requester organization scope. Requires features: api_keys.delete

Parameters

NameInRequiredSchemaDescription
idqueryYesanyAPI key identifier to delete

Responses

200Key deleted successfully
Content-Type: application/json
{
  "success": true
}
400Missing or invalid identifier
Content-Type: application/json
{
  "error": "string"
}
404Key not found within scope
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/api_keys/keys?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Dictionaries

Showing 11 of 11 endpoints
GET/api/dictionaries
Auth requireddictionaries.view

List dictionaries

Returns dictionaries accessible to the current organization, optionally including inactive records. Requires features: dictionaries.view

Parameters

NameInRequiredSchemaDescription
includeInactivequeryNoany

Responses

200Dictionary collection.
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "name": "string",
      "description": null,
      "isSystem": true,
      "isActive": true,
      "managerVisibility": null,
      "organizationId": null,
      "createdAt": "string",
      "updatedAt": null
    }
  ]
}
500Failed to load dictionaries
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/dictionaries" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/dictionaries
Auth requireddictionaries.manage

Create dictionary

Registers a dictionary scoped to the current organization. Requires features: dictionaries.manage

Request body (application/json)

{
  "key": "string",
  "name": "string"
}

Responses

201Dictionary created.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "key": "string",
  "name": "string",
  "description": null,
  "isSystem": true,
  "isActive": true,
  "managerVisibility": null,
  "organizationId": null,
  "createdAt": "string",
  "updatedAt": null
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
409Dictionary key already exists
Content-Type: application/json
{
  "error": "string"
}
500Failed to create dictionary
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/dictionaries" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"key\": \"string\",
  \"name\": \"string\"
}"
GET/api/dictionaries/{dictionaryId}
Auth requireddictionaries.view

Get dictionary

Returns details for the specified dictionary, including inheritance flags. Requires features: dictionaries.view

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany

Responses

200Dictionary details.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "key": "string",
  "name": "string",
  "description": null,
  "isSystem": true,
  "isActive": true,
  "managerVisibility": null,
  "organizationId": null,
  "createdAt": "string",
  "updatedAt": null
}
400Invalid parameters
Content-Type: application/json
{
  "error": "string"
}
404Dictionary not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to load dictionary
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/dictionaries/{dictionaryId}
Auth requireddictionaries.manage

Update dictionary

Updates mutable attributes of the dictionary. Currency dictionaries are protected from modification. Requires features: dictionaries.manage

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany

Request body (application/json)

{}

Responses

200Dictionary updated.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "key": "string",
  "name": "string",
  "description": null,
  "isSystem": true,
  "isActive": true,
  "managerVisibility": null,
  "organizationId": null,
  "createdAt": "string",
  "updatedAt": null
}
400Validation failed or protected dictionary
Content-Type: application/json
{
  "error": "string"
}
404Dictionary not found
Content-Type: application/json
{
  "error": "string"
}
409Dictionary key already exists
Content-Type: application/json
{
  "error": "string"
}
500Failed to update dictionary
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
DELETE/api/dictionaries/{dictionaryId}
Auth requireddictionaries.manage

Delete dictionary

Soft deletes the dictionary unless it is the protected currency dictionary. Requires features: dictionaries.manage

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany

Responses

200Dictionary archived.
Content-Type: application/json
{
  "ok": true
}
400Protected dictionary cannot be deleted
Content-Type: application/json
{
  "error": "string"
}
404Dictionary not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to delete dictionary
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/dictionaries/{dictionaryId}/entries
Auth requireddictionaries.view

List dictionary entries

Returns entries for the specified dictionary ordered by position. Requires features: dictionaries.view

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany

Responses

200Dictionary entries.
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "value": "string",
      "label": "string",
      "color": null,
      "icon": null,
      "position": 1,
      "isDefault": true,
      "createdAt": "string",
      "updatedAt": null
    }
  ]
}
400Invalid parameters
Content-Type: application/json
{
  "error": "string"
}
404Dictionary not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to load dictionary entries
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000/entries" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/dictionaries/{dictionaryId}/entries
Auth requireddictionaries.manage

Create dictionary entry

Creates a new entry in the specified dictionary. Requires features: dictionaries.manage

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany

Request body (application/json)

{
  "value": "string",
  "color": null,
  "icon": null
}

Responses

201Dictionary entry created.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "value": "string",
  "label": "string",
  "color": null,
  "icon": null,
  "position": 1,
  "isDefault": true,
  "createdAt": "string",
  "updatedAt": null
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Dictionary not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to create dictionary entry
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000/entries" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"value\": \"string\",
  \"color\": null,
  \"icon\": null
}"
PATCH/api/dictionaries/{dictionaryId}/entries/{entryId}
Auth requireddictionaries.manage

Update dictionary entry

Updates the specified dictionary entry using the command bus pipeline. Requires features: dictionaries.manage

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany
entryIdpathYesany

Request body (application/json)

{
  "color": null,
  "icon": null
}

Responses

200Dictionary entry updated.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "value": "string",
  "label": "string",
  "color": null,
  "icon": null,
  "position": 1,
  "isDefault": true,
  "createdAt": "string",
  "updatedAt": null
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Dictionary or entry not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to update entry
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000/entries/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"color\": null,
  \"icon\": null
}"
DELETE/api/dictionaries/{dictionaryId}/entries/{entryId}
Auth requireddictionaries.manage

Delete dictionary entry

Deletes the specified dictionary entry via the command bus. Requires features: dictionaries.manage

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany
entryIdpathYesany

Responses

200Entry deleted.
Content-Type: application/json
{
  "ok": true
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Dictionary or entry not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to delete entry
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000/entries/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/dictionaries/{dictionaryId}/entries/reorder
Auth requireddictionaries.manage

Reorder dictionary entries

Updates the position of dictionary entries for drag-and-drop reordering. Requires features: dictionaries.manage

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany

Request body (application/json)

{
  "entries": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "position": 1
    }
  ]
}

Responses

200Entries reordered.
Content-Type: application/json
{
  "ok": true
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Dictionary not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to reorder entries
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000/entries/reorder" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"entries\": [
    {
      \"id\": \"00000000-0000-4000-8000-000000000000\",
      \"position\": 1
    }
  ]
}"
POST/api/dictionaries/{dictionaryId}/entries/set-default
Auth requireddictionaries.manage

Set default dictionary entry

Marks the specified entry as the default for this dictionary, clearing any previous default. Requires features: dictionaries.manage

Parameters

NameInRequiredSchemaDescription
dictionaryIdpathYesany

Request body (application/json)

{
  "entryId": "00000000-0000-4000-8000-000000000000"
}

Responses

200Default entry set.
Content-Type: application/json
{
  "ok": true
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Dictionary or entry not found
Content-Type: application/json
{
  "error": "string"
}
500Failed to set default entry
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/dictionaries/00000000-0000-4000-8000-000000000000/entries/set-default" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"entryId\": \"00000000-0000-4000-8000-000000000000\"
}"

Business Rules

Showing 17 of 17 endpoints
POST/api/business_rules/execute
Auth requiredbusiness_rules.execute

Execute rules for given context

Manually executes applicable business rules for the specified entity type, event, and data. Supports dry-run mode to test rules without executing actions. Requires features: business_rules.execute

Request body (application/json)

{
  "entityType": "string",
  "dryRun": false
}

Responses

200Rules executed successfully
Content-Type: application/json
{
  "allowed": true,
  "executedRules": [
    {
      "ruleId": "string",
      "ruleName": "string",
      "conditionResult": true,
      "executionTime": 1
    }
  ],
  "totalExecutionTime": 1
}
400Invalid request payload
Content-Type: application/json
{
  "error": "string"
}
500Execution error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/business_rules/execute" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"entityType\": \"string\",
  \"dryRun\": false
}"
POST/api/business_rules/execute/{ruleId}
Auth requiredbusiness_rules.execute

Execute a specific rule by its database UUID

Directly executes a specific business rule identified by its UUID, bypassing the normal entityType/eventType discovery mechanism. Useful for workflows and targeted rule execution. Requires features: business_rules.execute

Parameters

NameInRequiredSchemaDescription
ruleIdpathYesanyThe database UUID of the business rule to execute

Request body (application/json)

{
  "dryRun": false
}

Responses

200Rule executed successfully
Content-Type: application/json
{
  "success": true,
  "ruleId": "string",
  "ruleName": "string",
  "conditionResult": true,
  "actionsExecuted": null,
  "executionTime": 1
}
400Invalid request payload or rule ID
Content-Type: application/json
{
  "error": "string"
}
404Rule not found
Content-Type: application/json
{
  "error": "string"
}
500Execution error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/business_rules/execute/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"dryRun\": false
}"
GET/api/business_rules/logs
Auth requiredbusiness_rules.view_logs

List rule execution logs

Returns rule execution history for the current tenant and organization with filtering and pagination. Useful for audit trails and debugging. Requires features: business_rules.view_logs

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
ruleIdqueryNoany
entityIdqueryNoany
entityTypequeryNoany
executionResultqueryNoany
executedByqueryNoany
executedAtFromqueryNoany
executedAtToqueryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Rule execution logs collection
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "ruleId": "string",
      "ruleName": "string",
      "ruleType": "string",
      "entityId": "00000000-0000-4000-8000-000000000000",
      "entityType": "string",
      "executionResult": "SUCCESS",
      "inputContext": null,
      "outputContext": null,
      "errorMessage": null,
      "executionTimeMs": 1,
      "executedAt": "string",
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": null,
      "executedBy": null
    }
  ],
  "total": 1,
  "totalPages": 1
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/business_rules/logs?page=1&pageSize=50&sortDir=desc" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/business_rules/logs/{id}
Auth requiredbusiness_rules.view_logs

Get execution log detail

Returns detailed information about a specific rule execution, including full context and results. Requires features: business_rules.view_logs

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Log entry details
Content-Type: application/json
{
  "id": "string",
  "rule": {
    "id": "00000000-0000-4000-8000-000000000000",
    "ruleId": "string",
    "ruleName": "string",
    "ruleType": "string",
    "entityType": "string"
  },
  "entityId": "00000000-0000-4000-8000-000000000000",
  "entityType": "string",
  "executionResult": "SUCCESS",
  "inputContext": null,
  "outputContext": null,
  "errorMessage": null,
  "executionTimeMs": 1,
  "executedAt": "string",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": null,
  "executedBy": null
}
400Invalid log id
Content-Type: application/json
{
  "error": "string"
}
404Log entry not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/business_rules/logs/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/business_rules/rules
Auth requiredbusiness_rules.view

List business rules

Returns business rules for the current tenant and organization with filtering and pagination. Requires features: business_rules.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
ruleIdqueryNoany
ruleTypequeryNoany
entityTypequeryNoany
eventTypequeryNoany
enabledqueryNoany
ruleCategoryqueryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Business rules collection
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "ruleId": "string",
      "ruleName": "string",
      "description": null,
      "ruleType": "GUARD",
      "ruleCategory": null,
      "entityType": "string",
      "eventType": null,
      "enabled": true,
      "priority": 1,
      "version": 1,
      "effectiveFrom": null,
      "effectiveTo": null,
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/business_rules/rules?page=1&pageSize=50&sortDir=desc" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/business_rules/rules
Auth requiredbusiness_rules.manage

Create business rule

Creates a new business rule for the current tenant and organization. Requires features: business_rules.manage

Request body (application/json)

{
  "ruleId": "string",
  "ruleName": "string",
  "description": null,
  "ruleType": "GUARD",
  "ruleCategory": null,
  "entityType": "string",
  "eventType": null,
  "enabled": true,
  "priority": 100,
  "version": 1,
  "effectiveFrom": null,
  "effectiveTo": null,
  "tenantId": "string",
  "organizationId": "string",
  "createdBy": null,
  "conditionExpression": null,
  "successActions": null,
  "failureActions": null
}

Responses

201Business rule created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/business_rules/rules" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"ruleId\": \"string\",
  \"ruleName\": \"string\",
  \"description\": null,
  \"ruleType\": \"GUARD\",
  \"ruleCategory\": null,
  \"entityType\": \"string\",
  \"eventType\": null,
  \"enabled\": true,
  \"priority\": 100,
  \"version\": 1,
  \"effectiveFrom\": null,
  \"effectiveTo\": null,
  \"tenantId\": \"string\",
  \"organizationId\": \"string\",
  \"createdBy\": null,
  \"conditionExpression\": null,
  \"successActions\": null,
  \"failureActions\": null
}"
PUT/api/business_rules/rules
Auth requiredbusiness_rules.manage

Update business rule

Updates an existing business rule. Requires features: business_rules.manage

Request body (application/json)

{
  "description": null,
  "ruleCategory": null,
  "eventType": null,
  "enabled": true,
  "priority": 100,
  "version": 1,
  "effectiveFrom": null,
  "effectiveTo": null,
  "conditionExpression": null,
  "successActions": null,
  "failureActions": null,
  "id": "string"
}

Responses

200Business rule updated
Content-Type: application/json
{
  "ok": true
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Business rule not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/business_rules/rules" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"description\": null,
  \"ruleCategory\": null,
  \"eventType\": null,
  \"enabled\": true,
  \"priority\": 100,
  \"version\": 1,
  \"effectiveFrom\": null,
  \"effectiveTo\": null,
  \"conditionExpression\": null,
  \"successActions\": null,
  \"failureActions\": null,
  \"id\": \"string\"
}"
DELETE/api/business_rules/rules
Auth requiredbusiness_rules.manage

Delete business rule

Soft deletes a business rule by identifier. Requires features: business_rules.manage

Parameters

NameInRequiredSchemaDescription
idqueryYesanyBusiness rule identifier

Responses

200Business rule deleted
Content-Type: application/json
{
  "ok": true
}
400Invalid identifier
Content-Type: application/json
{
  "error": "string"
}
404Business rule not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/business_rules/rules?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/business_rules/rules/{id}
Auth requiredbusiness_rules.view

Fetch business rule by ID

Returns complete details of a business rule including conditions and actions. Requires features: business_rules.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Business rule detail
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "ruleId": "string",
  "ruleName": "string",
  "description": null,
  "ruleType": "GUARD",
  "ruleCategory": null,
  "entityType": "string",
  "eventType": null,
  "successActions": null,
  "failureActions": null,
  "enabled": true,
  "priority": 1,
  "version": 1,
  "effectiveFrom": null,
  "effectiveTo": null,
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "createdBy": null,
  "updatedBy": null,
  "createdAt": "string",
  "updatedAt": "string"
}
400Invalid identifier
Content-Type: application/json
{
  "error": "string"
}
404Business rule not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/business_rules/rules/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/business_rules/sets
Auth requiredbusiness_rules.view

List rule sets

Returns rule sets for the current tenant and organization with filtering and pagination. Requires features: business_rules.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
setIdqueryNoany
enabledqueryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Rule sets collection
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "setId": "string",
      "setName": "string",
      "description": null,
      "enabled": true,
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "createdBy": null,
      "updatedBy": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/business_rules/sets?page=1&pageSize=50&sortDir=asc" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/business_rules/sets
Auth requiredbusiness_rules.manage_sets

Create rule set

Creates a new rule set for organizing business rules. Requires features: business_rules.manage_sets

Request body (application/json)

{
  "setId": "string",
  "setName": "string",
  "description": null,
  "enabled": true,
  "tenantId": "string",
  "organizationId": "string",
  "createdBy": null
}

Responses

201Rule set created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/business_rules/sets" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"setId\": \"string\",
  \"setName\": \"string\",
  \"description\": null,
  \"enabled\": true,
  \"tenantId\": \"string\",
  \"organizationId\": \"string\",
  \"createdBy\": null
}"
PUT/api/business_rules/sets
Auth requiredbusiness_rules.manage_sets

Update rule set

Updates an existing rule set. Requires features: business_rules.manage_sets

Request body (application/json)

{
  "description": null,
  "enabled": true,
  "id": "string"
}

Responses

200Rule set updated
Content-Type: application/json
{
  "ok": true
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Rule set not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/business_rules/sets" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"description\": null,
  \"enabled\": true,
  \"id\": \"string\"
}"
DELETE/api/business_rules/sets
Auth requiredbusiness_rules.manage_sets

Delete rule set

Soft deletes a rule set by identifier. Requires features: business_rules.manage_sets

Parameters

NameInRequiredSchemaDescription
idqueryYesanyRule set identifier

Responses

200Rule set deleted
Content-Type: application/json
{
  "ok": true
}
400Invalid identifier
Content-Type: application/json
{
  "error": "string"
}
404Rule set not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/business_rules/sets?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/business_rules/sets/{id}
Auth requiredbusiness_rules.view

Get rule set detail

Returns detailed information about a specific rule set, including all member rules. Requires features: business_rules.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Rule set details
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "setId": "string",
  "setName": "string",
  "description": null,
  "enabled": true,
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "createdBy": null,
  "updatedBy": null,
  "createdAt": "string",
  "updatedAt": "string",
  "members": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "ruleId": "00000000-0000-4000-8000-000000000000",
      "ruleName": "string",
      "ruleType": "string",
      "sequence": 1,
      "enabled": true
    }
  ]
}
400Invalid rule set id
Content-Type: application/json
{
  "error": "string"
}
404Rule set not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/business_rules/sets/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/business_rules/sets/{id}/members
Auth requiredbusiness_rules.manage_sets

Add rule to set

Adds a business rule to a rule set with specified sequence and enabled state. Requires features: business_rules.manage_sets

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "ruleId": "00000000-0000-4000-8000-000000000000",
  "sequence": 0,
  "enabled": true
}

Responses

201Member added
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Rule set or rule not found
Content-Type: application/json
{
  "error": "string"
}
409Rule already in set
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/business_rules/sets/:id/members" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"ruleId\": \"00000000-0000-4000-8000-000000000000\",
  \"sequence\": 0,
  \"enabled\": true
}"
PUT/api/business_rules/sets/{id}/members
Auth requiredbusiness_rules.manage_sets

Update set member

Updates sequence or enabled state of a rule set member. Requires features: business_rules.manage_sets

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "memberId": "00000000-0000-4000-8000-000000000000"
}

Responses

200Member updated
Content-Type: application/json
{
  "ok": true
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Member not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/business_rules/sets/:id/members" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"memberId\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/business_rules/sets/{id}/members
Auth requiredbusiness_rules.manage_sets

Remove rule from set

Removes a business rule from a rule set (hard delete). Requires features: business_rules.manage_sets

Parameters

NameInRequiredSchemaDescription
idpathYesany
memberIdqueryYesanyMember identifier

Responses

200Member removed
Content-Type: application/json
{
  "ok": true
}
400Invalid identifier
Content-Type: application/json
{
  "error": "string"
}
404Member not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/business_rules/sets/:id/members?memberId=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Feature Toggles

Showing 12 of 12 endpoints
GET/api/feature_toggles/check/boolean
Auth required

Check if feature is enabled

Checks if a feature toggle is enabled for the current context.

Parameters

NameInRequiredSchemaDescription
identifierqueryYesanyFeature toggle identifier

Responses

200Feature status
Content-Type: application/json
{
  "enabled": true,
  "source": "override",
  "toggleId": "string",
  "identifier": "string",
  "tenantId": "string"
}
400Bad Request
Content-Type: application/json
{
  "error": "string"
}
404Tenant not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/feature_toggles/check/boolean?identifier=string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/feature_toggles/check/json
Auth required

Get json config

Gets the json configuration for a feature toggle.

Parameters

NameInRequiredSchemaDescription
identifierqueryYesanyFeature toggle identifier

Responses

200Json config
Content-Type: application/json
{
  "valueType": "json",
  "source": "override",
  "toggleId": "string",
  "identifier": "string",
  "tenantId": "string"
}
400Bad Request
Content-Type: application/json
{
  "error": "string"
}
404Tenant not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/feature_toggles/check/json?identifier=string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/feature_toggles/check/number
Auth required

Get number config

Gets the number configuration for a feature toggle.

Parameters

NameInRequiredSchemaDescription
identifierqueryYesanyFeature toggle identifier

Responses

200Number config
Content-Type: application/json
{
  "valueType": "number",
  "value": 1,
  "source": "override",
  "toggleId": "string",
  "identifier": "string",
  "tenantId": "string"
}
400Bad Request
Content-Type: application/json
{
  "error": "string"
}
404Tenant not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/feature_toggles/check/number?identifier=string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/feature_toggles/check/string
Auth required

Get string config

Gets the string configuration for a feature toggle.

Parameters

NameInRequiredSchemaDescription
identifierqueryYesanyFeature toggle identifier

Responses

200String config
Content-Type: application/json
{
  "valueType": "string",
  "value": "string",
  "source": "override",
  "toggleId": "string",
  "identifier": "string",
  "tenantId": "string"
}
400Bad Request
Content-Type: application/json
{
  "error": "string"
}
404Tenant not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/feature_toggles/check/string?identifier=string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/feature_toggles/global
Auth requiredfeature_toggles.view

List global feature toggles

Returns all global feature toggles with filtering and pagination. Requires superadmin role. Requires features: feature_toggles.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoanyPage number for pagination
pageSizequeryNoanyNumber of items per page (max 200)
searchqueryNoanyCase-insensitive search across identifier, name, description, and category
typequeryNoanyFilter by toggle type (boolean, string, number, json)
categoryqueryNoanyFilter by category (case-insensitive partial match)
namequeryNoanyFilter by name (case-insensitive partial match)
identifierqueryNoanyFilter by identifier (case-insensitive partial match)
sortFieldqueryNoanyField to sort by
sortDirqueryNoanySort direction (ascending or descending)

Responses

200Feature toggles collection
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "identifier": "string",
      "name": "string",
      "description": null,
      "category": null,
      "type": "boolean",
      "defaultValue": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/feature_toggles/global?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/feature_toggles/global
Auth requiredfeature_toggles.manage

Create global feature toggle

Creates a new global feature toggle. Requires superadmin role. Requires features: feature_toggles.manage

Request body (application/json)

{
  "identifier": "string",
  "name": "string",
  "description": null,
  "category": null,
  "type": "boolean",
  "defaultValue": null
}

Responses

201Feature toggle created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/feature_toggles/global" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"identifier\": \"string\",
  \"name\": \"string\",
  \"description\": null,
  \"category\": null,
  \"type\": \"boolean\",
  \"defaultValue\": null
}"
PUT/api/feature_toggles/global
Auth requiredfeature_toggles.manage

Update global feature toggle

Updates an existing global feature toggle. Requires superadmin role. Requires features: feature_toggles.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "description": null,
  "category": null,
  "defaultValue": null
}

Responses

200Feature toggle updated
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Feature toggle not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/feature_toggles/global" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"description\": null,
  \"category\": null,
  \"defaultValue\": null
}"
DELETE/api/feature_toggles/global
Auth requiredfeature_toggles.manage

Delete global feature toggle

Soft deletes a global feature toggle by ID. Requires superadmin role. Requires features: feature_toggles.manage

Parameters

NameInRequiredSchemaDescription
idqueryYesanyFeature toggle identifier

Responses

200Feature toggle deleted
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Invalid identifier
Content-Type: application/json
{
  "error": "string"
}
404Feature toggle not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/feature_toggles/global?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/feature_toggles/global/{id}
Auth requiredfeature_toggles.view

Fetch feature toggle by ID

Returns complete details of a feature toggle. Requires features: feature_toggles.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Feature toggle detail
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "identifier": "string",
  "name": "string",
  "description": null,
  "category": null,
  "type": "boolean",
  "defaultValue": null
}
400Invalid identifier
Content-Type: application/json
{
  "error": "string"
}
404Feature toggle not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/feature_toggles/global/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/feature_toggles/global/{id}/override
Auth requiredfeature_toggles.view

Fetch feature toggle override

Returns feature toggle override. Requires features: feature_toggles.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Feature toggle overrides
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantName": "string",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "toggleType": "boolean"
}
400Invalid request
Content-Type: application/json
{
  "error": "string"
}
404Feature toggle not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/feature_toggles/global/:id/override" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/feature_toggles/overrides
Auth requiredfeature_toggles.view

List overrides

Returns list of feature toggle overrides. Requires features: feature_toggles.view

Parameters

NameInRequiredSchemaDescription
categoryqueryNoany
namequeryNoany
identifierqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
pagequeryNoany
pageSizequeryNoany

Responses

200List of overrides
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "toggleId": "00000000-0000-4000-8000-000000000000",
      "overrideState": "enabled",
      "identifier": "string",
      "name": "string",
      "category": null,
      "defaultState": true,
      "tenantName": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1,
  "isSuperAdmin": true
}
400Invalid query parameters
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/feature_toggles/overrides?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/feature_toggles/overrides
Auth requiredfeature_toggles.manage

Change override state

Enable, disable or inherit a feature toggle for a specific tenant. Requires features: feature_toggles.manage

Request body (application/json)

{
  "toggleId": "00000000-0000-4000-8000-000000000000",
  "isOverride": true
}

Responses

200Override updated
Content-Type: application/json
{
  "ok": true,
  "overrideToggleId": null
}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/feature_toggles/overrides" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"toggleId\": \"00000000-0000-4000-8000-000000000000\",
  \"isOverride\": true
}"

Workflows

Showing 20 of 21 endpoints
GET/api/workflows/definitions

List workflow definitions

Get a list of workflow definitions with optional filters. Supports pagination and search.

Parameters

NameInRequiredSchemaDescription
workflowIdqueryYesany
enabledqueryNoany
searchqueryNoany
limitqueryNoany
offsetqueryNoany

Responses

200List of workflow definitions with pagination
Content-Type: application/json
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workflowId": "checkout-flow",
      "workflowName": "Checkout Flow",
      "description": "Complete checkout workflow for processing orders",
      "version": 1,
      "definition": {
        "steps": [
          {
            "stepId": "start",
            "stepName": "Start",
            "stepType": "START"
          },
          {
            "stepId": "validate-cart",
            "stepName": "Validate Cart",
            "stepType": "AUTOMATED"
          },
          {
            "stepId": "end",
            "stepName": "End",
            "stepType": "END"
          }
        ],
        "transitions": [
          {
            "transitionId": "start-to-validate",
            "fromStepId": "start",
            "toStepId": "validate-cart",
            "trigger": "auto"
          },
          {
            "transitionId": "validate-to-end",
            "fromStepId": "validate-cart",
            "toStepId": "end",
            "trigger": "auto"
          }
        ]
      },
      "enabled": true,
      "tenantId": "123e4567-e89b-12d3-a456-426614174001",
      "organizationId": "123e4567-e89b-12d3-a456-426614174002",
      "createdAt": "2025-12-08T10:00:00.000Z",
      "updatedAt": "2025-12-08T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/definitions?workflowId=string&limit=50&offset=0" \
  -H "Accept: application/json"
POST/api/workflows/definitions

Create workflow definition

Create a new workflow definition. The definition must include at least START and END steps with at least one transition connecting them.

Request body (application/json)

{
  "workflowId": "checkout-flow",
  "workflowName": "Checkout Flow",
  "description": "Complete checkout workflow for processing orders",
  "version": 1,
  "definition": {
    "steps": [
      {
        "stepId": "start",
        "stepName": "Start",
        "stepType": "START"
      },
      {
        "stepId": "validate-cart",
        "stepName": "Validate Cart",
        "stepType": "AUTOMATED",
        "description": "Validate cart items and check inventory"
      },
      {
        "stepId": "payment",
        "stepName": "Process Payment",
        "stepType": "AUTOMATED",
        "description": "Charge payment method",
        "retryPolicy": {
          "maxAttempts": 3,
          "backoffMs": 1000
        }
      },
      {
        "stepId": "end",
        "stepName": "End",
        "stepType": "END"
      }
    ],
    "transitions": [
      {
        "transitionId": "start-to-validate",
        "fromStepId": "start",
        "toStepId": "validate-cart",
        "trigger": "auto"
      },
      {
        "transitionId": "validate-to-payment",
        "fromStepId": "validate-cart",
        "toStepId": "payment",
        "trigger": "auto"
      },
      {
        "transitionId": "payment-to-end",
        "fromStepId": "payment",
        "toStepId": "end",
        "trigger": "auto",
        "activities": [
          {
            "activityName": "Send Order Confirmation",
            "activityType": "SEND_EMAIL",
            "config": {
              "to": "{{context.customerEmail}}",
              "subject": "Order Confirmation #{{context.orderId}}",
              "template": "order_confirmation"
            }
          }
        ]
      }
    ]
  },
  "enabled": true
}

Responses

201Workflow definition created successfully
Content-Type: application/json
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "workflowId": "checkout-flow",
    "workflowName": "Checkout Flow",
    "description": "Complete checkout workflow for processing orders",
    "version": 1,
    "definition": {
      "steps": [
        {
          "stepId": "start",
          "stepName": "Start",
          "stepType": "START"
        },
        {
          "stepId": "validate-cart",
          "stepName": "Validate Cart",
          "stepType": "AUTOMATED"
        },
        {
          "stepId": "payment",
          "stepName": "Process Payment",
          "stepType": "AUTOMATED"
        },
        {
          "stepId": "end",
          "stepName": "End",
          "stepType": "END"
        }
      ],
      "transitions": [
        {
          "transitionId": "start-to-validate",
          "fromStepId": "start",
          "toStepId": "validate-cart",
          "trigger": "auto"
        },
        {
          "transitionId": "validate-to-payment",
          "fromStepId": "validate-cart",
          "toStepId": "payment",
          "trigger": "auto"
        },
        {
          "transitionId": "payment-to-end",
          "fromStepId": "payment",
          "toStepId": "end",
          "trigger": "auto"
        }
      ]
    },
    "enabled": true,
    "tenantId": "123e4567-e89b-12d3-a456-426614174001",
    "organizationId": "123e4567-e89b-12d3-a456-426614174002",
    "createdAt": "2025-12-08T10:00:00.000Z",
    "updatedAt": "2025-12-08T10:00:00.000Z"
  },
  "message": "Workflow definition created successfully"
}
400Validation error - invalid workflow structure
Content-Type: application/json
{
  "error": "Validation failed",
  "details": [
    {
      "code": "invalid_type",
      "message": "Workflow must have at least START and END steps",
      "path": [
        "definition",
        "steps"
      ]
    }
  ]
}
409Conflict - workflow with same ID and version already exists
Content-Type: application/json
{
  "error": "Workflow definition with ID \"checkout-flow\" and version 1 already exists"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/definitions" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"workflowId\": \"string\",
  \"workflowName\": \"string\",
  \"description\": null,
  \"version\": 1,
  \"definition\": {
    \"steps\": [
      {
        \"stepId\": \"string\",
        \"stepName\": \"string\",
        \"stepType\": \"START\"
      }
    ],
    \"transitions\": [
      {
        \"transitionId\": \"string\",
        \"fromStepId\": \"string\",
        \"toStepId\": \"string\",
        \"trigger\": \"auto\",
        \"continueOnActivityFailure\": false,
        \"priority\": 0
      }
    ]
  },
  \"metadata\": null,
  \"enabled\": true
}"
GET/api/workflows/definitions/{id}

Get workflow definition

Get a single workflow definition by ID. Returns the complete workflow structure including steps and transitions (with embedded activities).

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Workflow definition found
Content-Type: application/json
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "workflowId": "checkout-flow",
    "workflowName": "Checkout Flow",
    "description": "Complete checkout workflow for processing orders",
    "version": 1,
    "definition": {
      "steps": [
        {
          "stepId": "start",
          "stepName": "Start",
          "stepType": "START"
        },
        {
          "stepId": "validate-cart",
          "stepName": "Validate Cart",
          "stepType": "AUTOMATED",
          "description": "Validate cart items and check inventory"
        },
        {
          "stepId": "payment",
          "stepName": "Process Payment",
          "stepType": "AUTOMATED",
          "description": "Charge payment method",
          "retryPolicy": {
            "maxAttempts": 3,
            "backoffMs": 1000
          }
        },
        {
          "stepId": "end",
          "stepName": "End",
          "stepType": "END"
        }
      ],
      "transitions": [
        {
          "transitionId": "start-to-validate",
          "fromStepId": "start",
          "toStepId": "validate-cart",
          "trigger": "auto"
        },
        {
          "transitionId": "validate-to-payment",
          "fromStepId": "validate-cart",
          "toStepId": "payment",
          "trigger": "auto"
        },
        {
          "transitionId": "payment-to-end",
          "fromStepId": "payment",
          "toStepId": "end",
          "trigger": "auto",
          "activities": [
            {
              "activityName": "Send Order Confirmation",
              "activityType": "SEND_EMAIL",
              "config": {
                "to": "{{context.customerEmail}}",
                "subject": "Order Confirmation #{{context.orderId}}",
                "template": "order_confirmation"
              }
            }
          ]
        }
      ]
    },
    "enabled": true,
    "tenantId": "123e4567-e89b-12d3-a456-426614174001",
    "organizationId": "123e4567-e89b-12d3-a456-426614174002",
    "createdAt": "2025-12-08T10:00:00.000Z",
    "updatedAt": "2025-12-08T10:00:00.000Z"
  }
}
404Workflow definition not found
Content-Type: application/json
{
  "error": "Workflow definition not found"
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/definitions/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"
PUT/api/workflows/definitions/{id}

Update workflow definition

Update an existing workflow definition. Supports partial updates - only provided fields will be updated.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "definition": {
    "steps": [
      {
        "stepId": "start",
        "stepName": "Start",
        "stepType": "START"
      },
      {
        "stepId": "validate-cart",
        "stepName": "Validate Cart",
        "stepType": "AUTOMATED"
      },
      {
        "stepId": "payment",
        "stepName": "Process Payment",
        "stepType": "AUTOMATED"
      },
      {
        "stepId": "confirmation",
        "stepName": "Order Confirmation",
        "stepType": "AUTOMATED"
      },
      {
        "stepId": "end",
        "stepName": "End",
        "stepType": "END"
      }
    ],
    "transitions": [
      {
        "transitionId": "start-to-validate",
        "fromStepId": "start",
        "toStepId": "validate-cart",
        "trigger": "auto"
      },
      {
        "transitionId": "validate-to-payment",
        "fromStepId": "validate-cart",
        "toStepId": "payment",
        "trigger": "auto"
      },
      {
        "transitionId": "payment-to-confirmation",
        "fromStepId": "payment",
        "toStepId": "confirmation",
        "trigger": "auto"
      },
      {
        "transitionId": "confirmation-to-end",
        "fromStepId": "confirmation",
        "toStepId": "end",
        "trigger": "auto"
      }
    ]
  },
  "enabled": true
}

Responses

200Workflow definition updated successfully
Content-Type: application/json
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "workflowId": "checkout-flow",
    "workflowName": "Checkout Flow",
    "description": "Complete checkout workflow for processing orders",
    "version": 1,
    "definition": {
      "steps": [
        {
          "stepId": "start",
          "stepName": "Start",
          "stepType": "START"
        },
        {
          "stepId": "validate-cart",
          "stepName": "Validate Cart",
          "stepType": "AUTOMATED"
        },
        {
          "stepId": "payment",
          "stepName": "Process Payment",
          "stepType": "AUTOMATED"
        },
        {
          "stepId": "confirmation",
          "stepName": "Order Confirmation",
          "stepType": "AUTOMATED"
        },
        {
          "stepId": "end",
          "stepName": "End",
          "stepType": "END"
        }
      ],
      "transitions": [
        {
          "transitionId": "start-to-validate",
          "fromStepId": "start",
          "toStepId": "validate-cart",
          "trigger": "auto"
        },
        {
          "transitionId": "validate-to-payment",
          "fromStepId": "validate-cart",
          "toStepId": "payment",
          "trigger": "auto"
        },
        {
          "transitionId": "payment-to-confirmation",
          "fromStepId": "payment",
          "toStepId": "confirmation",
          "trigger": "auto"
        },
        {
          "transitionId": "confirmation-to-end",
          "fromStepId": "confirmation",
          "toStepId": "end",
          "trigger": "auto"
        }
      ]
    },
    "enabled": true,
    "tenantId": "123e4567-e89b-12d3-a456-426614174001",
    "organizationId": "123e4567-e89b-12d3-a456-426614174002",
    "createdAt": "2025-12-08T10:00:00.000Z",
    "updatedAt": "2025-12-08T11:30:00.000Z"
  },
  "message": "Workflow definition updated successfully"
}
400Validation error
Content-Type: application/json
{
  "error": "Validation failed",
  "details": [
    {
      "code": "invalid_type",
      "message": "Expected object, received string",
      "path": [
        "definition"
      ]
    }
  ]
}
404Workflow definition not found
Content-Type: application/json
{
  "error": "Workflow definition not found"
}

Example

curl -X PUT "https://api.open-mercato.local/api/workflows/definitions/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"description\": null,
  \"metadata\": null,
  \"effectiveFrom\": null,
  \"effectiveTo\": null
}"
DELETE/api/workflows/definitions/{id}

Delete workflow definition

Soft delete a workflow definition. Cannot be deleted if there are active workflow instances (RUNNING or WAITING status) using this definition.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Workflow definition deleted successfully
Content-Type: application/json
{
  "message": "Workflow definition deleted successfully"
}
404Workflow definition not found
Content-Type: application/json
{
  "error": "Workflow definition not found"
}
409Cannot delete - active workflow instances exist
Content-Type: application/json
{
  "error": "Cannot delete workflow definition with 3 active instance(s)"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/workflows/definitions/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"
GET/api/workflows/events

List all workflow events

Get a paginated list of all workflow events with filtering options

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
eventTypequeryNoany
workflowInstanceIdqueryNoany
userIdqueryNoany
occurredAtFromqueryNoany
occurredAtToqueryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200List of workflow events
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "workflowInstanceId": "00000000-0000-4000-8000-000000000000",
      "stepInstanceId": null,
      "eventType": "string",
      "occurredAt": "string",
      "userId": null,
      "workflowInstance": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/events?page=1&pageSize=50&sortField=occurredAt&sortDir=desc" \
  -H "Accept: application/json"
GET/api/workflows/events/{id}

Get workflow event by ID

Get detailed information about a specific workflow event

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Workflow event details
Content-Type: application/json
{
  "id": "string",
  "workflowInstanceId": "00000000-0000-4000-8000-000000000000",
  "stepInstanceId": null,
  "eventType": "string",
  "occurredAt": "string",
  "userId": null,
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "workflowInstance": null
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
404Workflow event not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/events/:id" \
  -H "Accept: application/json"
GET/api/workflows/instances

List workflow instances

Get a list of workflow instances with optional filters. Supports pagination and filtering by status, workflowId, correlationKey, etc.

Parameters

NameInRequiredSchemaDescription
workflowIdqueryNoany
statusqueryNoany
correlationKeyqueryNoany
entityTypequeryNoany
entityIdqueryNoany
limitqueryNoany
offsetqueryNoany

Responses

200List of workflow instances
Content-Type: application/json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "definitionId": "00000000-0000-4000-8000-000000000000",
      "workflowId": "string",
      "version": 1,
      "status": "RUNNING",
      "currentStepId": "string",
      "correlationKey": null,
      "metadata": null,
      "startedAt": "string",
      "completedAt": null,
      "pausedAt": null,
      "cancelledAt": null,
      "errorMessage": null,
      "errorDetails": null,
      "pendingTransition": null,
      "retryCount": 1,
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "createdAt": "string",
      "updatedAt": "string",
      "deletedAt": null
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/instances?limit=50&offset=0" \
  -H "Accept: application/json"
POST/api/workflows/instances

Start workflow instance

Start a new workflow instance from a workflow definition. The workflow will execute immediately.

Request body (application/json)

{
  "workflowId": "string"
}

Responses

201Workflow started successfully
Content-Type: application/json
{
  "data": {
    "instance": {
      "id": "00000000-0000-4000-8000-000000000000",
      "definitionId": "00000000-0000-4000-8000-000000000000",
      "workflowId": "string",
      "version": 1,
      "status": "RUNNING",
      "currentStepId": "string",
      "correlationKey": null,
      "metadata": null,
      "startedAt": "string",
      "completedAt": null,
      "pausedAt": null,
      "cancelledAt": null,
      "errorMessage": null,
      "errorDetails": null,
      "pendingTransition": null,
      "retryCount": 1,
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "createdAt": "string",
      "updatedAt": "string",
      "deletedAt": null
    },
    "execution": {
      "status": "RUNNING",
      "currentStep": "string",
      "message": "string"
    }
  },
  "message": "string"
}
400Bad request - Validation failed or definition disabled/invalid
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden - Insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
404Workflow definition not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/instances" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"workflowId\": \"string\"
}"
GET/api/workflows/instances/{id}

Get workflow instance

Get detailed information about a specific workflow instance including current state, context, and execution status.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Workflow instance details
Content-Type: application/json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "definitionId": "00000000-0000-4000-8000-000000000000",
    "workflowId": "string",
    "version": 1,
    "status": "RUNNING",
    "currentStepId": "string",
    "correlationKey": null,
    "metadata": null,
    "startedAt": "string",
    "completedAt": null,
    "pausedAt": null,
    "cancelledAt": null,
    "errorMessage": null,
    "errorDetails": null,
    "pendingTransition": null,
    "retryCount": 1,
    "tenantId": "00000000-0000-4000-8000-000000000000",
    "organizationId": "00000000-0000-4000-8000-000000000000",
    "createdAt": "string",
    "updatedAt": "string",
    "deletedAt": null
  }
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
404Workflow instance not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/instances/:id" \
  -H "Accept: application/json"
POST/api/workflows/instances/{id}/advance

Manually advance workflow to next step

Manually advance a workflow instance to the next step. Useful for manual progression, step-by-step testing, user-triggered transitions, and approval flows. Validates transitions and auto-progresses if possible.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

200Workflow advanced successfully
Content-Type: application/json
{
  "data": {
    "instance": {
      "id": "00000000-0000-4000-8000-000000000000",
      "status": "string",
      "currentStepId": null,
      "previousStepId": null,
      "transitionFired": null
    }
  },
  "message": "string"
}
400Invalid request, no valid transitions, or workflow already completed/cancelled/failed
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
404Workflow instance not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/instances/:id/advance" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/workflows/instances/{id}/cancel

Cancel workflow instance

Cancel a running or paused workflow instance. The workflow will be marked as CANCELLED and will not execute further.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Workflow cancelled successfully
Content-Type: application/json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "definitionId": "00000000-0000-4000-8000-000000000000",
    "workflowId": "string",
    "version": 1,
    "status": "RUNNING",
    "currentStepId": "string",
    "correlationKey": null,
    "metadata": null,
    "startedAt": "string",
    "completedAt": null,
    "pausedAt": null,
    "cancelledAt": null,
    "errorMessage": null,
    "errorDetails": null,
    "pendingTransition": null,
    "retryCount": 1,
    "tenantId": "00000000-0000-4000-8000-000000000000",
    "organizationId": "00000000-0000-4000-8000-000000000000",
    "createdAt": "string",
    "updatedAt": "string",
    "deletedAt": null
  },
  "message": "string"
}
400Bad request - Workflow cannot be cancelled in current status
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden - Insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
404Workflow instance not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/instances/:id/cancel" \
  -H "Accept: application/json"
GET/api/workflows/instances/{id}/events

Get workflow instance events

Get a chronological list of events for a workflow instance. Events track all state changes, transitions, and activities.

Parameters

NameInRequiredSchemaDescription
idpathYesany
eventTypequeryNoany
limitqueryNoany
offsetqueryNoany

Responses

200List of workflow events
Content-Type: application/json
{
  "data": [
    {
      "id": "string",
      "workflowInstanceId": "00000000-0000-4000-8000-000000000000",
      "stepInstanceId": null,
      "eventType": "string",
      "occurredAt": "string",
      "userId": null,
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
404Workflow instance not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/instances/:id/events?limit=100&offset=0" \
  -H "Accept: application/json"
POST/api/workflows/instances/{id}/retry

Retry failed workflow instance

Retry a failed workflow instance from its current step. The workflow will be reset to RUNNING status and execution will continue.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Workflow retry initiated successfully
Content-Type: application/json
{
  "data": {
    "instance": {
      "id": "00000000-0000-4000-8000-000000000000",
      "definitionId": "00000000-0000-4000-8000-000000000000",
      "workflowId": "string",
      "version": 1,
      "status": "RUNNING",
      "currentStepId": "string",
      "correlationKey": null,
      "metadata": null,
      "startedAt": "string",
      "completedAt": null,
      "pausedAt": null,
      "cancelledAt": null,
      "errorMessage": null,
      "errorDetails": null,
      "pendingTransition": null,
      "retryCount": 1,
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "createdAt": "string",
      "updatedAt": "string",
      "deletedAt": null
    },
    "execution": {
      "status": "RUNNING",
      "currentStep": "string",
      "events": [
        {
          "eventType": "string",
          "occurredAt": "string"
        }
      ],
      "executionTime": 1
    }
  },
  "message": "string"
}
400Bad request - Workflow cannot be retried in current status or execution error
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden - Insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
404Workflow instance not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/instances/:id/retry" \
  -H "Accept: application/json"
POST/api/workflows/instances/{id}/signal

Send signal to specific workflow

Sends a signal to a specific workflow instance waiting for a signal. The workflow must be in PAUSED status and waiting for the specified signal.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "signalName": "string"
}

Responses

200Signal sent successfully
Content-Type: application/json
{
  "success": true,
  "message": "string"
}
400Invalid request body or signal name mismatch
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
404Instance or definition not found
Content-Type: application/json
{
  "error": "string"
}
409Workflow not paused or not waiting for signal
Content-Type: application/json
{
  "error": "string"
}
500Internal server error or transition failed
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/instances/:id/signal" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"signalName\": \"string\"
}"
POST/api/workflows/instances/validate-start

Validate if workflow can be started

Evaluates pre-conditions defined on the START step and returns validation errors with localized messages if any fail. Returns canStart: true/false with details.

Request body (application/json)

{
  "workflowId": "string"
}

Responses

200Validation result (canStart, errors, validatedRules)
Content-Type: application/json
{
  "canStart": true,
  "workflowId": "string"
}
400Invalid request body or missing context
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/instances/validate-start" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"workflowId\": \"string\"
}"
POST/api/workflows/signals

Send signal to workflows by correlation key

Sends a signal to all workflow instances waiting for the specified signal that match the correlation key. Returns the count of workflows that received the signal.

Request body (application/json)

{
  "correlationKey": "string",
  "signalName": "string"
}

Responses

200Signal sent to matching workflows
Content-Type: application/json
{
  "success": true,
  "message": "string",
  "count": 1
}
400Missing tenant or organization context
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Insufficient permissions
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/signals" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"correlationKey\": \"string\",
  \"signalName\": \"string\"
}"
GET/api/workflows/tasks

List user tasks

Returns paginated list of user tasks with optional filtering by status, assignee, workflow instance, overdue, and myTasks flags.

Parameters

NameInRequiredSchemaDescription
statusqueryNoanyFilter by status (comma-separated for multiple: PENDING,IN_PROGRESS,COMPLETED,CANCELLED,ESCALATED)
assignedToqueryNoanyFilter by assigned user ID
workflowInstanceIdqueryNoanyFilter by workflow instance ID
overduequeryNoanyFilter overdue tasks (true/false)
myTasksqueryNoanyShow only tasks assigned to or claimable by current user
limitqueryNoanyNumber of results (max 100)
offsetqueryNoanyPagination offset

Responses

200User tasks list with pagination
Content-Type: application/json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "workflowInstanceId": "00000000-0000-4000-8000-000000000000",
      "stepInstanceId": "00000000-0000-4000-8000-000000000000",
      "taskName": "string",
      "description": null,
      "status": "PENDING",
      "formSchema": null,
      "formData": null,
      "assignedTo": null,
      "assignedToRoles": null,
      "claimedBy": null,
      "claimedAt": null,
      "dueDate": null,
      "escalatedAt": null,
      "escalatedTo": null,
      "completedBy": null,
      "completedAt": null,
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}
400Invalid query parameters or missing tenant context
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/tasks?limit=50&offset=0" \
  -H "Accept: application/json"
GET/api/workflows/tasks/{id}

Get task details

Returns complete details of a user task by ID.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200User task details
Content-Type: application/json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "workflowInstanceId": "00000000-0000-4000-8000-000000000000",
    "stepInstanceId": "00000000-0000-4000-8000-000000000000",
    "taskName": "string",
    "description": null,
    "status": "PENDING",
    "formSchema": null,
    "formData": null,
    "assignedTo": null,
    "assignedToRoles": null,
    "claimedBy": null,
    "claimedAt": null,
    "dueDate": null,
    "escalatedAt": null,
    "escalatedTo": null,
    "completedBy": null,
    "completedAt": null,
    "tenantId": "00000000-0000-4000-8000-000000000000",
    "organizationId": "00000000-0000-4000-8000-000000000000",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
400Missing tenant or organization context
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
404Task not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/workflows/tasks/:id" \
  -H "Accept: application/json"
POST/api/workflows/tasks/{id}/claim

Claim a task from role queue

Allows a user to claim a task assigned to their role(s). Once claimed, the task moves to IN_PROGRESS status and is assigned to the claiming user.

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Task claimed successfully
Content-Type: application/json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "workflowInstanceId": "00000000-0000-4000-8000-000000000000",
    "stepInstanceId": "00000000-0000-4000-8000-000000000000",
    "taskName": "string",
    "description": null,
    "status": "PENDING",
    "formSchema": null,
    "formData": null,
    "assignedTo": null,
    "assignedToRoles": null,
    "claimedBy": null,
    "claimedAt": null,
    "dueDate": null,
    "escalatedAt": null,
    "escalatedTo": null,
    "completedBy": null,
    "completedAt": null,
    "tenantId": "00000000-0000-4000-8000-000000000000",
    "organizationId": "00000000-0000-4000-8000-000000000000",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "message": "string"
}
400Missing tenant or organization context
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
404Task not found
Content-Type: application/json
{
  "error": "string"
}
409Task already claimed
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/workflows/tasks/:id/claim" \
  -H "Accept: application/json"

Search

Showing 15 of 15 endpoints
GET/api/search/embeddings
Auth requiredsearch.embeddings.view

Get embeddings configuration

Returns current embedding provider and model configuration. Requires features: search.embeddings.view

Responses

200Embeddings settings
Content-Type: application/json
{
  "settings": {
    "openaiConfigured": true,
    "autoIndexingEnabled": true,
    "autoIndexingLocked": true,
    "lockReason": null,
    "embeddingConfig": null,
    "configuredProviders": [
      "openai"
    ],
    "indexedDimension": null,
    "reindexRequired": true,
    "documentCount": null
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/search/embeddings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/search/embeddings
Auth requiredsearch.embeddings.manage

Update embeddings configuration

Updates the embedding provider and model settings. Requires features: search.embeddings.manage

Request body (application/json)

{}

Responses

200Updated settings
Content-Type: application/json
{
  "settings": {
    "openaiConfigured": true,
    "autoIndexingEnabled": true,
    "autoIndexingLocked": true,
    "lockReason": null,
    "embeddingConfig": null,
    "configuredProviders": [
      "openai"
    ],
    "indexedDimension": null,
    "reindexRequired": true,
    "documentCount": null
  }
}
400Invalid request
Content-Type: application/json
{
  "error": "string"
}
409Auto-indexing disabled via environment
Content-Type: application/json
{
  "error": "string"
}
500Update failed
Content-Type: application/json
{
  "error": "string"
}
503Configuration service unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/search/embeddings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/search/embeddings/reindex
Auth requiredsearch.embeddings.manage

Trigger vector reindex

Starts a vector embedding reindex operation. Requires features: search.embeddings.manage

Request body (application/json)

{}

Responses

200Reindex result
Content-Type: application/json
{
  "ok": true
}
409Reindex already in progress
Content-Type: application/json
{
  "error": "string",
  "lock": {
    "type": "fulltext",
    "action": "string",
    "startedAt": "string",
    "elapsedMinutes": 1,
    "processedCount": null,
    "totalCount": null
  }
}
500Reindex failed
Content-Type: application/json
{
  "error": "string"
}
503Search indexer unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/search/embeddings/reindex" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/search/embeddings/reindex/cancel
Auth requiredsearch.embeddings.manage

Cancel vector reindex

Cancels an in-progress vector reindex operation. Requires features: search.embeddings.manage

Responses

200Cancel result
Content-Type: application/json
{
  "ok": true,
  "jobsRemoved": 1
}

Example

curl -X POST "https://api.open-mercato.local/api/search/embeddings/reindex/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/search/index
Auth requiredsearch.view

List vector index entries

Returns paginated list of entries in the vector search index. Requires features: search.view

Parameters

NameInRequiredSchemaDescription
entityIdqueryNoanyFilter by entity ID (e.g., "customers:customer_person_profile", "catalog:catalog_product")
limitqueryNoanyMaximum entries to return (default: 50, max: 200)
offsetqueryNoanyOffset for pagination (default: 0)

Responses

200Index entries
Content-Type: application/json
{
  "entries": [
    {
      "id": "string",
      "entityId": "string",
      "recordId": "string",
      "tenantId": "string",
      "organizationId": null
    }
  ],
  "limit": 1,
  "offset": 1
}
500Failed to fetch index
Content-Type: application/json
{
  "error": "string"
}
503Vector strategy unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/search/index" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/search/index
Auth requiredsearch.embeddings.manage

Purge vector index

Purges entries from the vector search index. Requires confirmAll=true when purging all entities. Requires features: search.embeddings.manage

Parameters

NameInRequiredSchemaDescription
entityIdqueryNoanySpecific entity ID to purge (e.g., "customers:customer_person_profile", "catalog:catalog_product")
confirmAllqueryNoanyRequired when purging all entities

Responses

200Purge result
Content-Type: application/json
{
  "ok": true
}
400Missing confirmAll parameter
Content-Type: application/json
{
  "error": "string"
}
500Purge failed
Content-Type: application/json
{
  "error": "string"
}
503Search indexer unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/search/index" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/search/reindex
Auth requiredsearch.reindex

Trigger fulltext reindex

Starts a fulltext (Meilisearch) reindex operation. Can clear, recreate, or fully reindex. Requires features: search.reindex

Request body (application/json)

{}

Responses

200Reindex result
Content-Type: application/json
{
  "ok": true,
  "action": "clear",
  "entityId": null
}
409Reindex already in progress
Content-Type: application/json
{
  "error": "string",
  "lock": {
    "type": "fulltext",
    "action": "string",
    "startedAt": "string",
    "elapsedMinutes": 1,
    "processedCount": null,
    "totalCount": null
  }
}
500Reindex failed
Content-Type: application/json
{
  "error": "string"
}
503Search service unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/search/reindex" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/search/reindex/cancel
Auth requiredsearch.reindex

Cancel fulltext reindex

Cancels an in-progress fulltext reindex operation. Requires features: search.reindex

Responses

200Cancel result
Content-Type: application/json
{
  "ok": true,
  "jobsRemoved": 1
}

Example

curl -X POST "https://api.open-mercato.local/api/search/reindex/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/search/search/global
Auth requiredsearch.view

Global search (Cmd+K)

Performs a global search using saved tenant strategies. Does NOT accept strategies from URL. Requires features: search.view

Parameters

NameInRequiredSchemaDescription
qqueryYesanySearch query (required)
limitqueryNoanyMaximum results to return (default: 50, max: 100)
entityTypesqueryNoanyComma-separated entity types to filter results (e.g., "customers:customer_person_profile,catalog:catalog_product,sales:sales_order")

Responses

200Search results
Content-Type: application/json
{
  "results": [
    {
      "entityId": "string",
      "recordId": "string",
      "score": 1,
      "source": "fulltext"
    }
  ],
  "strategiesUsed": [
    "fulltext"
  ],
  "strategiesEnabled": [
    "fulltext"
  ],
  "timing": 1,
  "query": "string",
  "limit": 1
}
400Missing query parameter
Content-Type: application/json
{
  "error": "string"
}
500Search failed
Content-Type: application/json
{
  "error": "string"
}
503Search service unavailable
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/search/search/global?q=string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/search/settings
Auth requiredsearch.view

Get search settings and status

Returns search module configuration, available strategies, and reindex lock status. Requires features: search.view

Responses

200Search settings
Content-Type: application/json
{
  "settings": {
    "strategies": [
      {
        "id": "string",
        "name": "string",
        "priority": 1,
        "available": true
      }
    ],
    "fulltextConfigured": true,
    "fulltextStats": null,
    "vectorConfigured": true,
    "tokensEnabled": true,
    "defaultStrategies": [
      "string"
    ],
    "reindexLock": null,
    "fulltextReindexLock": null,
    "vectorReindexLock": null
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/search/settings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/search/settings/fulltext
Auth requiredsearch.view

Get fulltext search configuration

Returns Meilisearch configuration status and index statistics. Requires features: search.view

Responses

200Fulltext settings
Content-Type: application/json
{
  "driver": null,
  "configured": true,
  "envVars": {
    "MEILISEARCH_HOST": {
      "set": true,
      "hint": "string"
    },
    "MEILISEARCH_API_KEY": {
      "set": true,
      "hint": "string"
    }
  },
  "optionalEnvVars": {
    "MEILISEARCH_INDEX_PREFIX": {
      "set": true,
      "hint": "string"
    },
    "SEARCH_EXCLUDE_ENCRYPTED_FIELDS": {
      "set": true,
      "hint": "string"
    }
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/search/settings/fulltext" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/search/settings/global-search
Auth requiredsearch.manage

Update global search strategies

Sets which strategies are enabled for Cmd+K global search. Requires features: search.manage

Request body (application/json)

{
  "enabledStrategies": [
    "fulltext"
  ]
}

Responses

200Updated settings
Content-Type: application/json
{
  "ok": true,
  "enabledStrategies": [
    "fulltext"
  ]
}
400Invalid request
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/search/settings/global-search" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"enabledStrategies\": [
    \"fulltext\"
  ]
}"
GET/api/search/settings/vector-store
Auth requiredsearch.view

Get vector store configuration

Returns vector store configuration status. Requires features: search.view

Responses

200Vector store settings
Content-Type: application/json
{
  "currentDriver": "pgvector",
  "configured": true,
  "drivers": [
    {
      "id": "pgvector",
      "name": "string",
      "configured": true,
      "implemented": true,
      "envVars": [
        {
          "name": "string",
          "set": true,
          "hint": "string"
        }
      ]
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/search/settings/vector-store" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Currencies

Showing 14 of 14 endpoints
GET/api/currencies/currencies
Auth requiredcurrencies.view

List currencies

Returns a paginated collection of currencies scoped to the authenticated organization. Requires features: currencies.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
isBasequeryNoany
isActivequeryNoany
codequeryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated currencies
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "code": "string",
      "name": "string",
      "symbol": null,
      "decimalPlaces": 1,
      "thousandsSeparator": null,
      "decimalSeparator": null,
      "isBase": true,
      "isActive": true,
      "createdAt": null,
      "updatedAt": null,
      "organizationId": "string",
      "tenantId": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/currencies/currencies?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/currencies/currencies
Auth requiredcurrencies.manage

Create currency

Creates a new currency. Requires features: currencies.manage

Request body (application/json)

{
  "organizationId": "string",
  "tenantId": "string",
  "code": "string",
  "name": "string",
  "symbol": null,
  "thousandsSeparator": null,
  "decimalSeparator": null
}

Responses

201Currency created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/currencies/currencies" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"string\",
  \"tenantId\": \"string\",
  \"code\": \"string\",
  \"name\": \"string\",
  \"symbol\": null,
  \"thousandsSeparator\": null,
  \"decimalSeparator\": null
}"
PUT/api/currencies/currencies
Auth requiredcurrencies.manage

Update currency

Updates an existing currency by id. Requires features: currencies.manage

Request body (application/json)

{
  "id": "string",
  "symbol": null,
  "thousandsSeparator": null,
  "decimalSeparator": null
}

Responses

200Currency updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/currencies/currencies" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\",
  \"symbol\": null,
  \"thousandsSeparator\": null,
  \"decimalSeparator\": null
}"
DELETE/api/currencies/currencies
Auth requiredcurrencies.manage

Delete currency

Deletes a currency by id. Requires features: currencies.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Currency deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/currencies/currencies" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/currencies/currencies/options
Auth requiredcurrencies.view

List currency options

Returns currencies formatted for select inputs. Requires features: currencies.view

Parameters

NameInRequiredSchemaDescription
qqueryNoany
queryqueryNoany
searchqueryNoany
includeInactivequeryNoany
limitqueryNoany

Responses

200Option list
Content-Type: application/json
{
  "items": [
    {
      "value": "string",
      "label": "string"
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "items": []
}

Example

curl -X GET "https://api.open-mercato.local/api/currencies/currencies/options?limit=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/currencies/exchange-rates
Auth requiredcurrencies.rates.view

List exchangerates

Returns a paginated collection of exchangerates scoped to the authenticated organization. Requires features: currencies.rates.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
sortFieldqueryNoany
sortDirqueryNoany
fromCurrencyCodequeryNoany
toCurrencyCodequeryNoany
isActivequeryNoany
sourcequeryNoany
typequeryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated exchangerates
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "fromCurrencyCode": "string",
      "toCurrencyCode": "string",
      "rate": "string",
      "date": "string",
      "source": "string",
      "type": null,
      "isActive": true,
      "createdAt": null,
      "updatedAt": null,
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "tenantId": "00000000-0000-4000-8000-000000000000"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/currencies/exchange-rates?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/currencies/exchange-rates
Auth requiredcurrencies.rates.manage

Create exchangerate

Creates a new exchange rate. Requires features: currencies.rates.manage

Request body (application/json)

{
  "organizationId": "string",
  "tenantId": "string",
  "fromCurrencyCode": "string",
  "toCurrencyCode": "string",
  "rate": "string",
  "type": null
}

Responses

201ExchangeRate created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/currencies/exchange-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"string\",
  \"tenantId\": \"string\",
  \"fromCurrencyCode\": \"string\",
  \"toCurrencyCode\": \"string\",
  \"rate\": \"string\",
  \"type\": null
}"
PUT/api/currencies/exchange-rates
Auth requiredcurrencies.rates.manage

Update exchangerate

Updates an existing exchange rate by id. Requires features: currencies.rates.manage

Request body (application/json)

{
  "id": "string",
  "type": null
}

Responses

200ExchangeRate updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/currencies/exchange-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\",
  \"type\": null
}"
DELETE/api/currencies/exchange-rates
Auth requiredcurrencies.rates.manage

Delete exchangerate

Deletes an exchange rate by id. Requires features: currencies.rates.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200ExchangeRate deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/currencies/exchange-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/currencies/fetch-configs

List currency fetch configurations

Returns all currency fetch configurations scoped to the authenticated organization.

Responses

200A list of currency fetch configurations
Content-Type: application/json
{
  "configs": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "provider": "string",
      "isEnabled": true,
      "syncTime": null,
      "lastSyncAt": null,
      "lastSyncStatus": null,
      "lastSyncMessage": null,
      "lastSyncCount": null,
      "config": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/currencies/fetch-configs" \
  -H "Accept: application/json"
POST/api/currencies/fetch-configs

Create currency fetch configuration

Creates a new currency fetch configuration.

Request body (application/json)

{
  "provider": "NBP",
  "isEnabled": false,
  "syncTime": null,
  "config": null
}

Responses

201Currency fetch configuration created successfully
Content-Type: application/json
{
  "config": {
    "id": "00000000-0000-4000-8000-000000000000",
    "organizationId": "00000000-0000-4000-8000-000000000000",
    "tenantId": "00000000-0000-4000-8000-000000000000",
    "provider": "string",
    "isEnabled": true,
    "syncTime": null,
    "lastSyncAt": null,
    "lastSyncStatus": null,
    "lastSyncMessage": null,
    "lastSyncCount": null,
    "config": null,
    "createdAt": "string",
    "updatedAt": "string"
  }
}
400Bad request
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/currencies/fetch-configs" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"provider\": \"NBP\",
  \"isEnabled\": false,
  \"syncTime\": null,
  \"config\": null
}"
PUT/api/currencies/fetch-configs

Update currency fetch configuration

Updates an existing currency fetch configuration by id.

Request body (application/json)

{
  "syncTime": null,
  "config": null,
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Currency fetch configuration updated successfully
Content-Type: application/json
{
  "config": {
    "id": "00000000-0000-4000-8000-000000000000",
    "organizationId": "00000000-0000-4000-8000-000000000000",
    "tenantId": "00000000-0000-4000-8000-000000000000",
    "provider": "string",
    "isEnabled": true,
    "syncTime": null,
    "lastSyncAt": null,
    "lastSyncStatus": null,
    "lastSyncMessage": null,
    "lastSyncCount": null,
    "config": null,
    "createdAt": "string",
    "updatedAt": "string"
  }
}
400Bad request
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/currencies/fetch-configs" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"syncTime\": null,
  \"config\": null,
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/currencies/fetch-configs

Delete currency fetch configuration

Deletes a currency fetch configuration by id.

Parameters

NameInRequiredSchemaDescription
idqueryYesanyCurrency fetch configuration identifier to delete

Responses

200Currency fetch configuration deleted successfully
Content-Type: application/json
{
  "success": true
}
400Bad request
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/currencies/fetch-configs?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"
POST/api/currencies/fetch-rates

Fetch currency rates

Fetches currency exchange rates from configured providers for a specific date.

Request body (application/json)

{}

Responses

200Currency rates fetched successfully
Content-Type: application/json
{
  "totalFetched": 1,
  "byProvider": {
    "key": {
      "count": 1
    }
  },
  "errors": [
    "string"
  ]
}
400Bad request
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "totalFetched": 1,
  "byProvider": {
    "key": {
      "count": 1
    }
  },
  "errors": [
    "string"
  ]
}

Example

curl -X POST "https://api.open-mercato.local/api/currencies/fetch-rates" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{}"

Resources

Showing 2 of 2 endpoints
POST/api/resources/resources/tags/assign
Auth requiredresources.manage_resources

Assign resource tag

Assigns a tag to a resources resource. Requires features: resources.manage_resources

Request body (application/json)

{
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tagId": "00000000-0000-4000-8000-000000000000",
  "resourceId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Tag assignment created
Content-Type: application/json
{
  "id": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/resources/resources/tags/assign" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tagId\": \"00000000-0000-4000-8000-000000000000\",
  \"resourceId\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/resources/resources/tags/unassign
Auth requiredresources.manage_resources

Unassign resource tag

Removes a tag from a resources resource. Requires features: resources.manage_resources

Request body (application/json)

{
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tagId": "00000000-0000-4000-8000-000000000000",
  "resourceId": "00000000-0000-4000-8000-000000000000"
}

Responses

200Tag assignment removed
Content-Type: application/json
{
  "id": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/resources/resources/tags/unassign" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tagId\": \"00000000-0000-4000-8000-000000000000\",
  \"resourceId\": \"00000000-0000-4000-8000-000000000000\"
}"

Staff

Showing 6 of 6 endpoints
POST/api/staff/leave-requests/accept
Auth requiredstaff.leave_requests.manage

Approve leave request

Approves a leave request and adds unavailability rules for the staff member. Requires features: staff.leave_requests.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "decisionComment": null,
  "decidedByUserId": null
}

Responses

200Leave request approved
Content-Type: application/json
{
  "ok": true,
  "id": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/staff/leave-requests/accept" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"decisionComment\": null,
  \"decidedByUserId\": null
}"
POST/api/staff/leave-requests/reject
Auth requiredstaff.leave_requests.manage

Reject leave request

Rejects a leave request with an optional comment. Requires features: staff.leave_requests.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "decisionComment": null,
  "decidedByUserId": null
}

Responses

200Leave request rejected
Content-Type: application/json
{
  "ok": true,
  "id": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/staff/leave-requests/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"decisionComment\": null,
  \"decidedByUserId\": null
}"
GET/api/staff/team-members/self
Auth requiredstaff.leave_requests.send

Get current user team member profile

Returns the staff team member linked to the current user, if any. Requires features: staff.leave_requests.send

Responses

200Team member profile
Content-Type: application/json
{
  "member": null
}

Example

curl -X GET "https://api.open-mercato.local/api/staff/team-members/self" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/staff/team-members/self
Auth requiredstaff.leave_requests.send

Create current user team member profile

Creates a team member profile for the signed-in user. Requires features: staff.leave_requests.send

Request body (application/json)

{
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "displayName": "string",
  "description": null
}

Responses

201Team member created
Content-Type: application/json
{
  "id": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
409Already exists
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/staff/team-members/self" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"displayName\": \"string\",
  \"description\": null
}"
POST/api/staff/team-members/tags/assign
Auth requiredstaff.manage_team

Assign team member tag

Assigns a tag to a staff team member. Requires features: staff.manage_team

Request body (application/json)

{
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "memberId": "00000000-0000-4000-8000-000000000000",
  "tag": "string"
}

Responses

201Tag assignment created
Content-Type: application/json
{
  "id": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/staff/team-members/tags/assign" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"memberId\": \"00000000-0000-4000-8000-000000000000\",
  \"tag\": \"string\"
}"
POST/api/staff/team-members/tags/unassign
Auth requiredstaff.manage_team

Unassign team member tag

Removes a tag from a staff team member. Requires features: staff.manage_team

Request body (application/json)

{
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "memberId": "00000000-0000-4000-8000-000000000000",
  "tag": "string"
}

Responses

200Tag assignment removed
Content-Type: application/json
{
  "id": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/staff/team-members/tags/unassign" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"memberId\": \"00000000-0000-4000-8000-000000000000\",
  \"tag\": \"string\"
}"

Events

Showing 2 of 2 endpoints
GET/api/events
Auth required

List declared events

Returns every declared event. Filters: category, module, excludeTriggerExcluded (default true).

Responses

200Declared events
Content-Type: application/json
{
  "data": [
    {
      "id": "string",
      "label": "string"
    }
  ],
  "total": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/events" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/events/stream
Auth required

GET /api/events/stream

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/events/stream" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Notifications

Showing 13 of 13 endpoints
GET/api/notifications
Auth required

List notifications

Returns a paginated collection of notifications.

Parameters

NameInRequiredSchemaDescription
statusqueryNoany
typequeryNoany
severityqueryNoany
sourceEntityTypequeryNoany
sourceEntityIdqueryNoany
sincequeryNoany
pagequeryNoany
pageSizequeryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated notifications
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "type": "string",
      "title": "string",
      "body": null,
      "titleKey": null,
      "bodyKey": null,
      "titleVariables": null,
      "bodyVariables": null,
      "icon": null,
      "severity": "string",
      "status": "string",
      "actions": [
        {
          "id": "string",
          "label": "string"
        }
      ],
      "sourceModule": null,
      "sourceEntityType": null,
      "sourceEntityId": null,
      "linkHref": null,
      "createdAt": "string",
      "readAt": null,
      "actionTaken": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/notifications?page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/notifications
Auth requirednotifications.create

Create notification

Creates a notification for a user. Requires features: notifications.create

Request body (application/json)

{
  "type": "string",
  "severity": "info",
  "recipientUserId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Notification created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/notifications" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"type\": \"string\",
  \"severity\": \"info\",
  \"recipientUserId\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/notifications/{id}/action
Auth required

POST /api/notifications/{id}/action

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/notifications/:id/action" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/notifications/{id}/dismiss
Auth required

PUT /api/notifications/{id}/dismiss

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/notifications/:id/dismiss" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/notifications/{id}/read
Auth required

PUT /api/notifications/{id}/read

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/notifications/:id/read" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/notifications/{id}/restore
Auth required

PUT /api/notifications/{id}/restore

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/notifications/:id/restore" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/notifications/batch
Auth requirednotifications.create

POST /api/notifications/batch

Requires features: notifications.create

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/notifications/batch" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/notifications/feature
Auth requirednotifications.create

POST /api/notifications/feature

Requires features: notifications.create

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/notifications/feature" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/notifications/mark-all-read
Auth required

PUT /api/notifications/mark-all-read

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/notifications/mark-all-read" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/notifications/role
Auth requirednotifications.create

POST /api/notifications/role

Requires features: notifications.create

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/notifications/role" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/notifications/settings
Auth requirednotifications.manage

GET /api/notifications/settings

Requires features: notifications.manage

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/notifications/settings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/notifications/settings
Auth requirednotifications.manage

POST /api/notifications/settings

Requires features: notifications.manage

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/notifications/settings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/notifications/unread-count
Auth required

GET /api/notifications/unread-count

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/notifications/unread-count" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Progress

Showing 6 of 6 endpoints
GET/api/progress/active
Auth required

GET /api/progress/active

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/progress/active" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/progress/jobs
Auth required

List progressjobs

Returns a paginated collection of progressjobs scoped to the authenticated tenant.

Parameters

NameInRequiredSchemaDescription
statusqueryNoany
jobTypequeryNoany
parentJobIdqueryNoany
includeCompletedqueryNoany
completedSincequeryNoany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated progressjobs
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "jobType": "string",
      "name": "string",
      "description": null,
      "status": "string",
      "progressPercent": 1,
      "processedCount": 1,
      "totalCount": null,
      "etaSeconds": null,
      "cancellable": true,
      "startedAt": null,
      "finishedAt": null,
      "errorMessage": null,
      "createdAt": null,
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/progress/jobs?page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/progress/jobs
Auth requiredprogress.create

Create progressjob

Creates a new progress job for tracking a long-running operation. Requires features: progress.create

Request body (application/json)

{
  "jobType": "string",
  "name": "string",
  "cancellable": false
}

Responses

201ProgressJob created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/progress/jobs" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"jobType\": \"string\",
  \"name\": \"string\",
  \"cancellable\": false
}"
GET/api/progress/jobs/{id}
Auth required

GET /api/progress/jobs/{id}

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/progress/jobs/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/progress/jobs/{id}
Auth requiredprogress.update

PUT /api/progress/jobs/{id}

Requires features: progress.update

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/progress/jobs/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/progress/jobs/{id}
Auth requiredprogress.cancel

DELETE /api/progress/jobs/{id}

Requires features: progress.cancel

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

204Success

No response body.

Example

curl -X DELETE "https://api.open-mercato.local/api/progress/jobs/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Integrations

Showing 8 of 8 endpoints
GET/api/integrations
Auth requiredintegrations.view

List integrations

Returns a paginated collection of integrations. Requires features: integrations.view

Parameters

NameInRequiredSchemaDescription
qqueryNoany
categoryqueryNoany
bundleIdqueryNoany
isEnabledqueryNoany
healthStatusqueryNoany
sortqueryNoany
orderqueryNoany
pagequeryNoany
pageSizequeryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated integrations
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "title": "string",
      "description": null,
      "category": null,
      "tags": [
        "string"
      ],
      "hub": null,
      "providerKey": null,
      "bundleId": null,
      "author": null,
      "company": null,
      "version": null,
      "hasCredentials": true,
      "isEnabled": true,
      "apiVersion": null,
      "healthStatus": "healthy",
      "lastHealthCheckedAt": null,
      "lastHealthLatencyMs": null,
      "enabledAt": null,
      "analytics": {
        "lastActivityAt": null,
        "totalCount": 1,
        "errorCount": 1,
        "errorRate": 1,
        "dailyCounts": [
          1
        ]
      }
    }
  ],
  "total": 1,
  "totalPages": 1,
  "bundles": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "icon": null,
      "integrationCount": 1,
      "enabledCount": 1
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/integrations?order=asc&page=1&pageSize=100" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/integrations/{id}
Auth requiredintegrations.view

Get integration detail

Requires features: integrations.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/integrations/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/integrations/{id}/credentials
Auth requiredintegrations.credentials.manage

Get or save integration credentials

Requires features: integrations.credentials.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/integrations/:id/credentials" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/integrations/{id}/credentials
Auth requiredintegrations.credentials.manage

Get or save integration credentials

Requires features: integrations.credentials.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/integrations/:id/credentials" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/integrations/{id}/health
Auth requiredintegrations.manage

Run health check for an integration

Requires features: integrations.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/integrations/:id/health" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/integrations/{id}/state
Auth requiredintegrations.manage

Update integration state

Requires features: integrations.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/integrations/:id/state" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/integrations/{id}/version
Auth requiredintegrations.manage

Change integration API version

Requires features: integrations.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/integrations/:id/version" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/integrations/logs
Auth requiredintegrations.manage

List integration logs

Requires features: integrations.manage

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/integrations/logs" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Data Sync

Showing 11 of 11 endpoints
GET/api/data_sync/mappings
Auth requireddata_sync.configure

List or create field mappings

Requires features: data_sync.configure

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/data_sync/mappings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/data_sync/mappings
Auth requireddata_sync.configure

List or create field mappings

Requires features: data_sync.configure

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/data_sync/mappings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/data_sync/mappings/{id}
Auth requireddata_sync.configure

Get, update, or delete a field mapping

Requires features: data_sync.configure

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/data_sync/mappings/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/data_sync/mappings/{id}
Auth requireddata_sync.configure

Get, update, or delete a field mapping

Requires features: data_sync.configure

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/data_sync/mappings/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/data_sync/mappings/{id}
Auth requireddata_sync.configure

Get, update, or delete a field mapping

Requires features: data_sync.configure

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

204Success

No response body.

Example

curl -X DELETE "https://api.open-mercato.local/api/data_sync/mappings/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/data_sync/runs/{id}
Auth requireddata_sync.view

Get sync run detail

Requires features: data_sync.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/data_sync/runs/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/data_sync/schedules
Auth requireddata_sync.configure

List or create sync schedules

Requires features: data_sync.configure

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/data_sync/schedules" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/data_sync/schedules
Auth requireddata_sync.configure

List or create sync schedules

Requires features: data_sync.configure

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/data_sync/schedules" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/data_sync/schedules/{id}
Auth requireddata_sync.configure

Manage a sync schedule

Requires features: data_sync.configure

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/data_sync/schedules/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/data_sync/schedules/{id}
Auth requireddata_sync.configure

Manage a sync schedule

Requires features: data_sync.configure

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/data_sync/schedules/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/data_sync/schedules/{id}
Auth requireddata_sync.configure

Manage a sync schedule

Requires features: data_sync.configure

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

204Success

No response body.

Example

curl -X DELETE "https://api.open-mercato.local/api/data_sync/schedules/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Messages

Showing 20 of 24 endpoints
GET/api/messages
Auth required

List messages

Parameters

NameInRequiredSchemaDescription
folderqueryNoany
statusqueryNoany
typequeryNoany
visibilityqueryNoany
sourceEntityTypequeryNoany
sourceEntityIdqueryNoany
externalEmailqueryNoany
hasObjectsqueryNoany
hasAttachmentsqueryNoany
hasActionsqueryNoany
senderIdqueryNoany
searchqueryNoany
sincequeryNoany
pagequeryNoany
pageSizequeryNoany

Responses

200Message list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "type": "string",
      "visibility": null,
      "sourceEntityType": null,
      "sourceEntityId": null,
      "externalEmail": null,
      "externalName": null,
      "subject": "string",
      "bodyPreview": "string",
      "senderUserId": "00000000-0000-4000-8000-000000000000",
      "senderName": null,
      "senderEmail": null,
      "priority": "string",
      "status": "string",
      "hasObjects": true,
      "objectCount": 1,
      "hasAttachments": true,
      "attachmentCount": 1,
      "recipientCount": 1,
      "hasActions": true,
      "actionTaken": null,
      "sentAt": null,
      "readAt": null,
      "threadId": null
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/messages?folder=inbox&page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/messages
Auth requiredmessages.compose

Compose a message

Requires features: messages.compose

Request body (application/json)

{
  "type": "default",
  "visibility": null,
  "recipients": [],
  "subject": "",
  "body": "",
  "bodyFormat": "text",
  "priority": "normal",
  "sendViaEmail": false,
  "isDraft": false
}

Responses

201Message created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "threadId": null
}

Example

curl -X POST "https://api.open-mercato.local/api/messages" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"type\": \"default\",
  \"visibility\": null,
  \"recipients\": [],
  \"subject\": \"\",
  \"body\": \"\",
  \"bodyFormat\": \"text\",
  \"priority\": \"normal\",
  \"sendViaEmail\": false,
  \"isDraft\": false
}"
GET/api/messages/{id}
Auth required

Get message detail

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Message detail with actor-visible thread items only
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "type": "string",
  "isDraft": true,
  "canEditDraft": true,
  "visibility": null,
  "sourceEntityType": null,
  "sourceEntityId": null,
  "externalEmail": null,
  "externalName": null,
  "typeDefinition": {
    "labelKey": "string",
    "icon": "string",
    "color": null,
    "allowReply": true,
    "allowForward": true,
    "ui": null
  },
  "threadId": null,
  "parentMessageId": null,
  "senderUserId": "00000000-0000-4000-8000-000000000000",
  "senderName": null,
  "senderEmail": null,
  "subject": "string",
  "body": "string",
  "bodyFormat": "text",
  "priority": "string",
  "sentAt": null,
  "actionData": null,
  "actionTaken": null,
  "actionTakenAt": null,
  "actionTakenByUserId": null,
  "recipients": [
    {
      "userId": "00000000-0000-4000-8000-000000000000",
      "type": "to",
      "status": "string",
      "readAt": null
    }
  ],
  "objects": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "entityModule": "string",
      "entityType": "string",
      "entityId": "00000000-0000-4000-8000-000000000000",
      "actionRequired": true,
      "actionType": null,
      "actionLabel": null,
      "snapshot": null,
      "preview": null
    }
  ],
  "thread": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "senderUserId": "00000000-0000-4000-8000-000000000000",
      "senderName": null,
      "senderEmail": null,
      "body": "string",
      "sentAt": null
    }
  ],
  "isRead": true
}
403Access denied
Content-Type: application/json
{
  "error": "string"
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/messages/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/messages/{id}
Auth requiredmessages.compose

Update draft message

Requires features: messages.compose

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "visibility": null
}

Responses

200Draft updated
Content-Type: application/json
{
  "ok": true
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}
409Only drafts can be edited
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/messages/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"visibility\": null
}"
DELETE/api/messages/{id}
Auth requiredmessages.view

Delete message for current sender/recipient context

Requires features: messages.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Message deleted
Content-Type: application/json
{
  "ok": true
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/messages/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/messages/{id}/actions/{actionId}
Auth requiredmessages.actions

Execute message action

Requires features: messages.actions

Parameters

NameInRequiredSchemaDescription
idpathYesany
actionIdpathYesany

Request body (application/json)

"string"

Responses

200Action executed
Content-Type: application/json
{
  "ok": true,
  "actionId": "string"
}
404Action not found
Content-Type: application/json
"string"
409Action already taken
Content-Type: application/json
"string"
410Action expired
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/messages/:id/actions/:actionId" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/messages/{id}/archive
Auth requiredmessages.view

Archive message

Requires features: messages.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Message archived
Content-Type: application/json
{
  "ok": true
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/messages/:id/archive" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/messages/{id}/archive
Auth requiredmessages.view

Unarchive message

Requires features: messages.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Message unarchived
Content-Type: application/json
{
  "ok": true
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/messages/:id/archive" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/messages/{id}/attachments
Auth required

List message attachments

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Attachments
Content-Type: application/json
{
  "attachments": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "fileName": "string",
      "fileSize": 1,
      "mimeType": "string",
      "url": "string"
    }
  ]
}
403Access denied
Content-Type: application/json
{
  "error": "string"
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/messages/:id/attachments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/messages/{id}/attachments
Auth requiredmessages.attach_files

Link attachments to draft message

Requires features: messages.attach_files

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "attachmentIds": [
    "00000000-0000-4000-8000-000000000000"
  ]
}

Responses

200Attachments linked
Content-Type: application/json
{
  "ok": true
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}
409Only draft messages can be edited
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/messages/:id/attachments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"attachmentIds\": [
    \"00000000-0000-4000-8000-000000000000\"
  ]
}"
DELETE/api/messages/{id}/attachments
Auth requiredmessages.attach_files

Unlink attachments from draft message

Requires features: messages.attach_files

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

200Attachments unlinked
Content-Type: application/json
{
  "ok": true
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}
409Only draft messages can be edited
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/messages/:id/attachments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/messages/{id}/confirmation
Auth required

Read message confirmation status

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Confirmation status
Content-Type: application/json
{
  "messageId": "00000000-0000-4000-8000-000000000000",
  "confirmed": true,
  "confirmedAt": null,
  "confirmedByUserId": null
}
403Access denied
Content-Type: application/json
{
  "error": "string"
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/messages/:id/confirmation" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/messages/{id}/conversation
Auth requiredmessages.view

Delete conversation for current actor

Requires features: messages.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Conversation deleted
Content-Type: application/json
{
  "ok": true,
  "affectedCount": 1
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/messages/:id/conversation" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/messages/{id}/conversation/archive
Auth requiredmessages.view

Archive conversation for current actor

Requires features: messages.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Conversation archived
Content-Type: application/json
{
  "ok": true,
  "affectedCount": 1
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/messages/:id/conversation/archive" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/messages/{id}/conversation/read
Auth requiredmessages.view

Mark entire conversation as unread for current actor

Requires features: messages.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Conversation marked unread
Content-Type: application/json
{
  "ok": true,
  "affectedCount": 1
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/messages/:id/conversation/read" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/messages/{id}/forward
Auth requiredmessages.compose

Forward a message and optionally include attachments from the forwarded conversation slice

Requires features: messages.compose

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "recipients": [
    {
      "userId": "00000000-0000-4000-8000-000000000000",
      "type": "to"
    }
  ],
  "includeAttachments": true,
  "sendViaEmail": false
}

Responses

201Message forwarded
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
404Message not found
Content-Type: application/json
"string"
409Forward not allowed for message type
Content-Type: application/json
"string"
413Forward body exceeds maximum length
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/messages/:id/forward" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"recipients\": [
    {
      \"userId\": \"00000000-0000-4000-8000-000000000000\",
      \"type\": \"to\"
    }
  ],
  \"includeAttachments\": true,
  \"sendViaEmail\": false
}"
GET/api/messages/{id}/forward-preview
Auth requiredmessages.compose

Get forward preview for a message

Requires features: messages.compose

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Forward preview generated
Content-Type: application/json
{
  "subject": "string",
  "body": "string"
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}
413Forward body exceeds maximum length
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/messages/:id/forward-preview" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/messages/{id}/read
Auth requiredmessages.view

Mark message as read

Requires features: messages.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Message marked read
Content-Type: application/json
{
  "ok": true
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/messages/:id/read" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/messages/{id}/read
Auth requiredmessages.view

Mark message as unread

Requires features: messages.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Message marked unread
Content-Type: application/json
{
  "ok": true
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/messages/:id/read" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/messages/{id}/reply
Auth requiredmessages.compose

Reply to message

Requires features: messages.compose

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "body": "string",
  "bodyFormat": "text",
  "replyAll": false,
  "sendViaEmail": false
}

Responses

201Reply created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
404Message not found
Content-Type: application/json
{
  "error": "string"
}
409No recipients available for reply
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/messages/:id/reply" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"body\": \"string\",
  \"bodyFormat\": \"text\",
  \"replyAll\": false,
  \"sendViaEmail\": false
}"

Ai Assistant

Showing 1 of 1 endpoints
POST/api/ai_assistant/session-key
Auth requiredai_assistant.view

Generate session key

Generates a new session token that can be included in MCP tool calls via the _sessionToken parameter. The token inherits the calling user's roles and organization context. Requires features: ai_assistant.view

Responses

200Session key created successfully
Content-Type: application/json
{
  "sessionToken": "string",
  "expiresAt": "string"
}
500Failed to create session key
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/session-key" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Translations

Showing 3 of 3 endpoints
GET/api/translations/{entityType}/{entityId}
Auth requiredtranslations.view

Get entity translations

Returns the full translation record for a single entity. Requires features: translations.view

Parameters

NameInRequiredSchemaDescription
entityTypepathYesany
entityIdpathYesany

Responses

200Translation record found.
Content-Type: application/json
"string"
404No translations found for this entity
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/translations/string/string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/translations/{entityType}/{entityId}
Auth requiredtranslations.manage

Create or update entity translations

Full replacement of translations JSONB for an entity. Requires features: translations.manage

Parameters

NameInRequiredSchemaDescription
entityTypepathYesany
entityIdpathYesany

Responses

200Translations saved.
Content-Type: application/json
"string"
400Validation failed
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/translations/string/string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/translations/{entityType}/{entityId}
Auth requiredtranslations.manage

Delete entity translations

Removes all translations for an entity. Requires features: translations.manage

Parameters

NameInRequiredSchemaDescription
entityTypepathYesany
entityIdpathYesany

Responses

204Translations deleted.

No response body.

Example

curl -X DELETE "https://api.open-mercato.local/api/translations/string/string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Scheduler

Showing 8 of 8 endpoints
GET/api/scheduler/jobs
Auth requiredscheduler.jobs.view

List scheduledjobs

Returns a paginated collection of scheduledjobs scoped to the authenticated organization. Requires features: scheduler.jobs.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
idqueryNoany
searchqueryNoany
scopeTypequeryNoany
isEnabledqueryYesany
sourceTypequeryNoany
sourceModulequeryNoany
sortqueryNoany
orderqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated scheduledjobs
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "description": null,
      "scopeType": "system",
      "organizationId": null,
      "tenantId": null,
      "scheduleType": "cron",
      "scheduleValue": "string",
      "timezone": "string",
      "targetType": "queue",
      "targetQueue": null,
      "targetCommand": null,
      "targetPayload": null,
      "requireFeature": null,
      "isEnabled": true,
      "lastRunAt": null,
      "nextRunAt": null,
      "sourceType": "user",
      "sourceModule": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/scheduler/jobs?page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/scheduler/jobs
Auth requiredscheduler.jobs.manage

Create scheduledjob

Creates a new scheduled job with cron or interval-based scheduling. Requires features: scheduler.jobs.manage

Request body (application/json)

{
  "name": "string",
  "description": null,
  "scopeType": "system",
  "organizationId": null,
  "tenantId": null,
  "scheduleType": "cron",
  "scheduleValue": "string",
  "timezone": "UTC",
  "targetType": "queue",
  "targetQueue": null,
  "targetCommand": null,
  "targetPayload": null,
  "requireFeature": null,
  "isEnabled": true,
  "sourceType": "user",
  "sourceModule": null
}

Responses

201ScheduledJob created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/scheduler/jobs" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"description\": null,
  \"scopeType\": \"system\",
  \"organizationId\": null,
  \"tenantId\": null,
  \"scheduleType\": \"cron\",
  \"scheduleValue\": \"string\",
  \"timezone\": \"UTC\",
  \"targetType\": \"queue\",
  \"targetQueue\": null,
  \"targetCommand\": null,
  \"targetPayload\": null,
  \"requireFeature\": null,
  \"isEnabled\": true,
  \"sourceType\": \"user\",
  \"sourceModule\": null
}"
PUT/api/scheduler/jobs
Auth requiredscheduler.jobs.manage

Update scheduledjob

Updates an existing scheduled job by ID. Requires features: scheduler.jobs.manage

Request body (application/json)

{
  "id": "string",
  "description": null,
  "targetQueue": null,
  "targetCommand": null,
  "targetPayload": null,
  "requireFeature": null
}

Responses

200ScheduledJob updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/scheduler/jobs" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\",
  \"description\": null,
  \"targetQueue\": null,
  \"targetCommand\": null,
  \"targetPayload\": null,
  \"requireFeature\": null
}"
DELETE/api/scheduler/jobs
Auth requiredscheduler.jobs.manage

Delete scheduledjob

Deletes a scheduled job by ID. Requires features: scheduler.jobs.manage

Request body (application/json)

{
  "id": "string"
}

Responses

200ScheduledJob deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/scheduler/jobs" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\"
}"
GET/api/scheduler/jobs/{id}/executions

Get execution history for a schedule

Fetch recent executions from BullMQ for a scheduled job. Requires QUEUE_STRATEGY=async.

Parameters

NameInRequiredSchemaDescription
idpathYesany
pageSizequeryNoany

Responses

200Execution history
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "scheduleId": "00000000-0000-4000-8000-000000000000",
      "startedAt": "string",
      "finishedAt": null,
      "status": "running",
      "triggerType": "scheduled",
      "triggeredByUserId": null,
      "errorMessage": null,
      "errorStack": null,
      "durationMs": null,
      "queueJobId": "string",
      "queueName": "string",
      "attemptsMade": 1,
      "result": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1
}
400Local strategy not supported
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Access denied
Content-Type: application/json
{
  "error": "string"
}
404Schedule not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/scheduler/jobs/:id/executions?pageSize=20" \
  -H "Accept: application/json"
GET/api/scheduler/queue-jobs/{jobId}

Get BullMQ job details and logs

Fetch detailed information and logs for a queue job. Requires QUEUE_STRATEGY=async.

Parameters

NameInRequiredSchemaDescription
jobIdpathYesany
queuequeryYesany

Responses

200Job details and logs
Content-Type: application/json
{
  "id": "string",
  "name": "string",
  "state": "waiting",
  "progress": null,
  "returnvalue": null,
  "failedReason": null,
  "stacktrace": null,
  "attemptsMade": 1,
  "processedOn": null,
  "finishedOn": null,
  "logs": [
    "string"
  ]
}
400Invalid request or local strategy not supported
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Access denied
Content-Type: application/json
{
  "error": "string"
}
404Job not found
Content-Type: application/json
{
  "error": "string"
}
500Internal server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/scheduler/queue-jobs/:jobId?queue=string" \
  -H "Accept: application/json"
GET/api/scheduler/targets

List available queues and commands

Returns all registered queue names (from module workers) and command IDs (from the command registry) that can be used as schedule targets.

Responses

200Available targets
Content-Type: application/json
{
  "queues": [
    {
      "value": "string",
      "label": "string"
    }
  ],
  "commands": [
    {
      "value": "string",
      "label": "string"
    }
  ]
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/scheduler/targets" \
  -H "Accept: application/json"
POST/api/scheduler/trigger

Manually trigger a schedule

Executes a scheduled job immediately, bypassing the scheduled time. Only works with async queue strategy.

Request body (application/json)

{
  "id": "string"
}

Responses

200Schedule triggered successfully
Content-Type: application/json
{
  "ok": true,
  "jobId": "string",
  "message": "string"
}
400Invalid request or local strategy not supported
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Access denied
Content-Type: application/json
{
  "error": "string"
}
404Schedule not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/scheduler/trigger" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\"
}"

Checkout

Showing 18 of 18 endpoints
POST/api/checkout/links
Auth requiredcheckout.create

POST /api/checkout/links

Requires features: checkout.create

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/checkout/links" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/checkout/pay/{slug}

GET /api/checkout/pay/{slug}

Parameters

NameInRequiredSchemaDescription
slugpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/checkout/pay/:slug" \
  -H "Accept: application/json"
GET/api/checkout/pay/{slug}/status/{transactionId}

GET /api/checkout/pay/{slug}/status/{transactionId}

Parameters

NameInRequiredSchemaDescription
slugpathYesany
transactionIdpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/checkout/pay/:slug/status/:transactionId" \
  -H "Accept: application/json"
POST/api/checkout/pay/{slug}/submit

POST /api/checkout/pay/{slug}/submit

Parameters

NameInRequiredSchemaDescription
slugpathYesany

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/checkout/pay/:slug/submit" \
  -H "Accept: application/json"
POST/api/checkout/pay/{slug}/verify-password

POST /api/checkout/pay/{slug}/verify-password

Parameters

NameInRequiredSchemaDescription
slugpathYesany

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/checkout/pay/:slug/verify-password" \
  -H "Accept: application/json"
GET/api/checkout/templates
Auth requiredcheckout.view

GET /api/checkout/templates

Requires features: checkout.view

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/checkout/templates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/checkout/templates
Auth requiredcheckout.create

POST /api/checkout/templates

Requires features: checkout.create

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/checkout/templates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/checkout/templates/{id}
Auth requiredcheckout.view

GET /api/checkout/templates/{id}

Requires features: checkout.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/checkout/templates/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/checkout/templates/{id}
Auth requiredcheckout.edit

PUT /api/checkout/templates/{id}

Requires features: checkout.edit

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/checkout/templates/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/checkout/templates/{id}
Auth requiredcheckout.delete

DELETE /api/checkout/templates/{id}

Requires features: checkout.delete

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

204Success

No response body.

Example

curl -X DELETE "https://api.open-mercato.local/api/checkout/templates/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/checkout/templates/{id}/preview
Auth requiredcheckout.view

GET /api/checkout/templates/{id}/preview

Requires features: checkout.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/checkout/templates/:id/preview" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/checkout/transactions
Auth requiredcheckout.view

GET /api/checkout/transactions

Requires features: checkout.view

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/checkout/transactions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/checkout/transactions/{id}
Auth requiredcheckout.view

GET /api/checkout/transactions/{id}

Requires features: checkout.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/checkout/transactions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/checkout/transactions/by-gateway/{gatewayTransactionId}
Auth requiredcheckout.view

GET /api/checkout/transactions/by-gateway/{gatewayTransactionId}

Requires features: checkout.view

Parameters

NameInRequiredSchemaDescription
gatewayTransactionIdpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/checkout/transactions/by-gateway/:gatewayTransactionId" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Sync Akeneo

Showing 6 of 6 endpoints
GET/api/sync_akeneo/custom-fields
Auth requireddata_sync.configure

Inspect and create Akeneo-backed custom fields

Requires features: data_sync.configure

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/sync_akeneo/custom-fields" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/sync_akeneo/custom-fields
Auth requireddata_sync.configure

Inspect and create Akeneo-backed custom fields

Requires features: data_sync.configure

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/sync_akeneo/custom-fields" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/sync_akeneo/delete-products
Auth requireddata_sync.configure

Start deleting all Akeneo-imported products for the current organization

Requires features: data_sync.configure

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/sync_akeneo/delete-products" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/sync_akeneo/discovery
Auth requireddata_sync.configure

Load Akeneo discovery metadata for field mapping

Requires features: data_sync.configure

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/sync_akeneo/discovery" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/sync_akeneo/first-import
Auth requireddata_sync.configure

GET /api/sync_akeneo/first-import

Requires features: data_sync.configure

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/sync_akeneo/first-import" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/sync_akeneo/first-import
Auth requireddata_sync.run

POST /api/sync_akeneo/first-import

Requires features: data_sync.run

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/sync_akeneo/first-import" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Webhooks

Showing 20 of 24 endpoints
GET/api/webhooks
Auth requiredwebhooks.view

List webhooks

Returns paginated webhooks for the current tenant and organization. Requires features: webhooks.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
isActivequeryNoany

Responses

200Webhook collection
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "description": null,
      "url": "string",
      "subscribedEvents": [
        "string"
      ],
      "httpMethod": "string",
      "isActive": true,
      "deliveryStrategy": "string",
      "maxRetries": 1,
      "consecutiveFailures": 1,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}
400Tenant context missing
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/webhooks
Auth requiredwebhooks.manage

Create webhook

Creates a new webhook endpoint. A signing secret (whsec_ prefixed) is auto-generated and returned once. Requires features: webhooks.manage

Request body (application/json)

{
  "name": "string",
  "description": null,
  "url": "https://example.com/resource",
  "subscribedEvents": [
    "string"
  ],
  "httpMethod": "POST",
  "customHeaders": null,
  "deliveryStrategy": "http",
  "strategyConfig": null,
  "maxRetries": 10,
  "timeoutMs": 15000,
  "rateLimitPerMinute": 0,
  "autoDisableThreshold": 100,
  "integrationId": null
}

Responses

201Webhook created
Content-Type: application/json
{
  "id": "string",
  "name": "string",
  "url": "string",
  "secret": "string",
  "subscribedEvents": [
    "string"
  ],
  "isActive": true
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/webhooks" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"description\": null,
  \"url\": \"https://example.com/resource\",
  \"subscribedEvents\": [
    \"string\"
  ],
  \"httpMethod\": \"POST\",
  \"customHeaders\": null,
  \"deliveryStrategy\": \"http\",
  \"strategyConfig\": null,
  \"maxRetries\": 10,
  \"timeoutMs\": 15000,
  \"rateLimitPerMinute\": 0,
  \"autoDisableThreshold\": 100,
  \"integrationId\": null
}"
GET/api/webhooks/{id}
Auth requiredwebhooks.view

Get webhook

Returns webhook configuration, masked secret metadata, and delivery settings. Requires features: webhooks.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Webhook detail
Content-Type: application/json
{
  "id": "string",
  "name": "string",
  "description": null,
  "url": "string",
  "subscribedEvents": [
    "string"
  ],
  "httpMethod": "string",
  "isActive": true,
  "deliveryStrategy": "string",
  "maxRetries": 1,
  "consecutiveFailures": 1,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "string",
  "updatedAt": "string",
  "customHeaders": null,
  "strategyConfig": null,
  "timeoutMs": 1,
  "rateLimitPerMinute": 1,
  "autoDisableThreshold": 1,
  "integrationId": null,
  "maskedSecret": "string",
  "previousSecretSetAt": null
}
404Webhook not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/webhooks/{id}
Auth requiredwebhooks.manage

Update webhook

Updates a single webhook configuration. Requires features: webhooks.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "description": null,
  "httpMethod": "POST",
  "customHeaders": null,
  "deliveryStrategy": "http",
  "strategyConfig": null,
  "maxRetries": 10,
  "timeoutMs": 15000,
  "rateLimitPerMinute": 0,
  "autoDisableThreshold": 100,
  "integrationId": null
}

Responses

200Webhook updated
Content-Type: application/json
{
  "id": "string",
  "name": "string",
  "description": null,
  "url": "string",
  "subscribedEvents": [
    "string"
  ],
  "httpMethod": "string",
  "isActive": true,
  "deliveryStrategy": "string",
  "maxRetries": 1,
  "consecutiveFailures": 1,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "string",
  "updatedAt": "string",
  "customHeaders": null,
  "strategyConfig": null,
  "timeoutMs": 1,
  "rateLimitPerMinute": 1,
  "autoDisableThreshold": 1,
  "integrationId": null,
  "maskedSecret": "string",
  "previousSecretSetAt": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Webhook not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/webhooks/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"description\": null,
  \"httpMethod\": \"POST\",
  \"customHeaders\": null,
  \"deliveryStrategy\": \"http\",
  \"strategyConfig\": null,
  \"maxRetries\": 10,
  \"timeoutMs\": 15000,
  \"rateLimitPerMinute\": 0,
  \"autoDisableThreshold\": 100,
  \"integrationId\": null
}"
DELETE/api/webhooks/{id}
Auth requiredwebhooks.manage

Delete webhook

Soft-deletes a webhook endpoint. Requires features: webhooks.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Webhook deleted
Content-Type: application/json
{
  "success": true
}
404Webhook not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/webhooks/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/webhooks/{id}/rotate-secret
Auth requiredwebhooks.secrets

Rotate secret

Returns the new secret once. Store it immediately; future reads only expose a masked value. Requires features: webhooks.secrets

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Secret rotated
Content-Type: application/json
{
  "success": true,
  "secret": "string",
  "previousSecretSetAt": null
}
404Webhook not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/webhooks/00000000-0000-4000-8000-000000000000/rotate-secret" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/webhooks/{id}/test
Auth requiredwebhooks.test

Test webhook

Creates a synthetic event payload and delivers it immediately without using the queue. Requires features: webhooks.test

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

200Test delivery result
Content-Type: application/json
{
  "success": true,
  "delivery": {
    "id": "string",
    "webhookId": "string",
    "eventType": "string",
    "messageId": "string",
    "status": "string",
    "responseStatus": null,
    "errorMessage": null,
    "attemptNumber": 1,
    "maxAttempts": 1,
    "targetUrl": "string",
    "durationMs": null,
    "enqueuedAt": "string",
    "lastAttemptAt": null,
    "deliveredAt": null,
    "createdAt": "string",
    "payload": {},
    "responseBody": null,
    "responseHeaders": null,
    "nextRetryAt": null,
    "updatedAt": "string"
  }
}
400Invalid request payload
Content-Type: application/json
{
  "error": "string"
}
404Webhook not found
Content-Type: application/json
{
  "error": "string"
}
409Webhook integration disabled
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/webhooks/00000000-0000-4000-8000-000000000000/test" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/webhooks/deliveries
Auth requiredwebhooks.view

List delivery logs

Returns paginated webhook delivery attempts with filtering by webhook, event type, and status. Requires features: webhooks.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
webhookIdqueryNoany
eventTypequeryNoany
statusqueryNoany

Responses

200Delivery log collection
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "webhookId": "string",
      "webhookName": null,
      "eventType": "string",
      "messageId": "string",
      "status": "string",
      "responseStatus": null,
      "errorMessage": null,
      "attemptNumber": 1,
      "maxAttempts": 1,
      "targetUrl": "string",
      "durationMs": null,
      "enqueuedAt": "string",
      "lastAttemptAt": null,
      "deliveredAt": null,
      "createdAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}
400Tenant context missing
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks/deliveries?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/webhooks/deliveries/{id}
Auth requiredwebhooks.view

Get delivery

Returns a single delivery attempt by ID. Requires features: webhooks.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Delivery detail
Content-Type: application/json
{
  "id": "string",
  "webhookId": "string",
  "eventType": "string",
  "messageId": "string",
  "status": "string",
  "responseStatus": null,
  "errorMessage": null,
  "attemptNumber": 1,
  "maxAttempts": 1,
  "targetUrl": "string",
  "durationMs": null,
  "enqueuedAt": "string",
  "lastAttemptAt": null,
  "deliveredAt": null,
  "createdAt": "string",
  "payload": {},
  "responseBody": null,
  "responseHeaders": null,
  "nextRetryAt": null,
  "updatedAt": "string"
}
404Delivery not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks/deliveries/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/webhooks/deliveries/{id}/retry
Auth requiredwebhooks.manage

Retry delivery

Resets retry scheduling fields and enqueues the delivery again. Requires features: webhooks.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Delivery re-enqueued
Content-Type: application/json
{
  "success": true,
  "delivery": {
    "id": "string",
    "webhookId": "string",
    "eventType": "string",
    "messageId": "string",
    "status": "string",
    "responseStatus": null,
    "errorMessage": null,
    "attemptNumber": 1,
    "maxAttempts": 1,
    "targetUrl": "string",
    "durationMs": null,
    "enqueuedAt": "string",
    "lastAttemptAt": null,
    "deliveredAt": null,
    "createdAt": "string",
    "payload": {},
    "responseBody": null,
    "responseHeaders": null,
    "nextRetryAt": null,
    "updatedAt": "string"
  }
}
404Delivery not found
Content-Type: application/json
{
  "error": "string"
}
409Webhook integration disabled
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/webhooks/deliveries/00000000-0000-4000-8000-000000000000/retry" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/webhooks/events
Auth requiredwebhooks.view

List webhook events

Returns all declared non-webhook events, sorted by event id. Requires features: webhooks.view

Responses

200Available events
Content-Type: application/json
{
  "data": [
    {
      "id": "string",
      "label": "string"
    }
  ],
  "total": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks/events" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/webhooks/inbound/{endpointId}

Receive inbound webhook

Endpoint ids currently resolve to registered adapter provider keys.

Parameters

NameInRequiredSchemaDescription
endpointIdpathYesany

Responses

200Inbound webhook accepted
Content-Type: application/json
{
  "ok": true
}
400Verification failed
Content-Type: application/json
{
  "error": "string"
}
404Endpoint not found
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
503Webhook integration disabled
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/webhooks/inbound/string" \
  -H "Accept: application/json"
GET/api/webhooks/webhook-deliveries
Auth requiredwebhooks.view

List delivery logs

Returns paginated webhook delivery attempts with filtering by webhook, event type, and status. Requires features: webhooks.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
webhookIdqueryNoany
eventTypequeryNoany
statusqueryNoany

Responses

200Delivery log collection
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "webhookId": "string",
      "webhookName": null,
      "eventType": "string",
      "messageId": "string",
      "status": "string",
      "responseStatus": null,
      "errorMessage": null,
      "attemptNumber": 1,
      "maxAttempts": 1,
      "targetUrl": "string",
      "durationMs": null,
      "enqueuedAt": "string",
      "lastAttemptAt": null,
      "deliveredAt": null,
      "createdAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}
400Tenant context missing
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks/webhook-deliveries?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/webhooks/webhook-deliveries/{id}
Auth requiredwebhooks.view

Get delivery

Returns a single delivery attempt by ID. Requires features: webhooks.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Delivery detail
Content-Type: application/json
{
  "id": "string",
  "webhookId": "string",
  "eventType": "string",
  "messageId": "string",
  "status": "string",
  "responseStatus": null,
  "errorMessage": null,
  "attemptNumber": 1,
  "maxAttempts": 1,
  "targetUrl": "string",
  "durationMs": null,
  "enqueuedAt": "string",
  "lastAttemptAt": null,
  "deliveredAt": null,
  "createdAt": "string",
  "payload": {},
  "responseBody": null,
  "responseHeaders": null,
  "nextRetryAt": null,
  "updatedAt": "string"
}
404Delivery not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks/webhook-deliveries/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/webhooks/webhook-deliveries/{id}/retry
Auth requiredwebhooks.manage

Retry delivery

Resets retry scheduling fields and enqueues the delivery again. Requires features: webhooks.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Delivery re-enqueued
Content-Type: application/json
{
  "success": true,
  "delivery": {
    "id": "string",
    "webhookId": "string",
    "eventType": "string",
    "messageId": "string",
    "status": "string",
    "responseStatus": null,
    "errorMessage": null,
    "attemptNumber": 1,
    "maxAttempts": 1,
    "targetUrl": "string",
    "durationMs": null,
    "enqueuedAt": "string",
    "lastAttemptAt": null,
    "deliveredAt": null,
    "createdAt": "string",
    "payload": {},
    "responseBody": null,
    "responseHeaders": null,
    "nextRetryAt": null,
    "updatedAt": "string"
  }
}
404Delivery not found
Content-Type: application/json
{
  "error": "string"
}
409Webhook integration disabled
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/webhooks/webhook-deliveries/00000000-0000-4000-8000-000000000000/retry" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/webhooks/webhooks
Auth requiredwebhooks.view

List webhooks

Returns paginated webhooks for the current tenant and organization. Requires features: webhooks.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
isActivequeryNoany

Responses

200Webhook collection
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "description": null,
      "url": "string",
      "subscribedEvents": [
        "string"
      ],
      "httpMethod": "string",
      "isActive": true,
      "deliveryStrategy": "string",
      "maxRetries": 1,
      "consecutiveFailures": 1,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}
400Tenant context missing
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks/webhooks" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/webhooks/webhooks
Auth requiredwebhooks.manage

Create webhook

Creates a new webhook endpoint. A signing secret (whsec_ prefixed) is auto-generated and returned once. Requires features: webhooks.manage

Request body (application/json)

{
  "name": "string",
  "description": null,
  "url": "https://example.com/resource",
  "subscribedEvents": [
    "string"
  ],
  "httpMethod": "POST",
  "customHeaders": null,
  "deliveryStrategy": "http",
  "strategyConfig": null,
  "maxRetries": 10,
  "timeoutMs": 15000,
  "rateLimitPerMinute": 0,
  "autoDisableThreshold": 100,
  "integrationId": null
}

Responses

201Webhook created
Content-Type: application/json
{
  "id": "string",
  "name": "string",
  "url": "string",
  "secret": "string",
  "subscribedEvents": [
    "string"
  ],
  "isActive": true
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/webhooks/webhooks" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"description\": null,
  \"url\": \"https://example.com/resource\",
  \"subscribedEvents\": [
    \"string\"
  ],
  \"httpMethod\": \"POST\",
  \"customHeaders\": null,
  \"deliveryStrategy\": \"http\",
  \"strategyConfig\": null,
  \"maxRetries\": 10,
  \"timeoutMs\": 15000,
  \"rateLimitPerMinute\": 0,
  \"autoDisableThreshold\": 100,
  \"integrationId\": null
}"
PUT/api/webhooks/webhooks
Auth requiredwebhooks.manage

Update webhook

Updates an existing webhook configuration. Requires features: webhooks.manage

Request body (application/json)

{
  "description": null,
  "httpMethod": "POST",
  "customHeaders": null,
  "deliveryStrategy": "http",
  "strategyConfig": null,
  "maxRetries": 10,
  "timeoutMs": 15000,
  "rateLimitPerMinute": 0,
  "autoDisableThreshold": 100,
  "integrationId": null
}

Responses

200Webhook updated
Content-Type: application/json
{
  "id": "string",
  "name": "string",
  "description": null,
  "url": "string",
  "subscribedEvents": [
    "string"
  ],
  "httpMethod": "string",
  "isActive": true,
  "deliveryStrategy": "string",
  "maxRetries": 1,
  "consecutiveFailures": 1,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "string",
  "updatedAt": "string",
  "customHeaders": null,
  "strategyConfig": null,
  "timeoutMs": 1,
  "rateLimitPerMinute": 1,
  "autoDisableThreshold": 1,
  "integrationId": null
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/webhooks/webhooks" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"description\": null,
  \"httpMethod\": \"POST\",
  \"customHeaders\": null,
  \"deliveryStrategy\": \"http\",
  \"strategyConfig\": null,
  \"maxRetries\": 10,
  \"timeoutMs\": 15000,
  \"rateLimitPerMinute\": 0,
  \"autoDisableThreshold\": 100,
  \"integrationId\": null
}"
DELETE/api/webhooks/webhooks
Auth requiredwebhooks.manage

Delete webhook

Soft-deletes a webhook endpoint. Requires features: webhooks.manage

Parameters

NameInRequiredSchemaDescription
idqueryYesanyWebhook ID to delete

Responses

200Deleted
Content-Type: application/json
{
  "success": true
}
404Not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/webhooks/webhooks?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/webhooks/webhooks/{id}
Auth requiredwebhooks.view

Get webhook

Returns webhook configuration, masked secret metadata, and delivery settings. Requires features: webhooks.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Webhook detail
Content-Type: application/json
{
  "id": "string",
  "name": "string",
  "description": null,
  "url": "string",
  "subscribedEvents": [
    "string"
  ],
  "httpMethod": "string",
  "isActive": true,
  "deliveryStrategy": "string",
  "maxRetries": 1,
  "consecutiveFailures": 1,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "string",
  "updatedAt": "string",
  "customHeaders": null,
  "strategyConfig": null,
  "timeoutMs": 1,
  "rateLimitPerMinute": 1,
  "autoDisableThreshold": 1,
  "integrationId": null,
  "maskedSecret": "string",
  "previousSecretSetAt": null
}
404Webhook not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/webhooks/webhooks/00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Participants

Showing 20 of 26 endpoints
GET/api/participants
Auth requiredparticipants.view

List participants

Returns a paginated collection of participants scoped to the authenticated organization. Requires features: participants.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
customerEntityIdqueryNoany
participantTypequeryNoany
modequeryNoany
segmentqueryNoany
capabilityModequeryNoany
capabilitySegmentqueryNoany
equipmentTypequeryNoany
coverageCountryCodequeryNoany
coverageRegionIdqueryNoany
requiresAdrqueryNoany
requiresReeferqueryNoany
requiresOversizedqueryNoany
minPayloadTonsqueryNoany
payoutCurrencyqueryNoany
payoutStatusqueryNoany
settlementReadyqueryNoany
searchqueryNoany
isVerifiedqueryNoany
nipqueryNoany
pagequeryNoany
pageSizequeryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Paginated participants
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "customerEntityId": null,
      "customerDisplayName": null,
      "customerPrimaryEmail": null,
      "customerPrimaryPhone": null,
      "customerStatus": null,
      "customerLifecycleStage": null,
      "participantType": null,
      "supportedModes": [
        "string"
      ],
      "supportedSegments": [
        "string"
      ],
      "nip": null,
      "regon": null,
      "krs": null,
      "vatEu": null,
      "eori": null,
      "fleetTrucks": 1,
      "fleetTrailers": 1,
      "fleetLocomotives": 1,
      "fleetWagons": 1,
      "fleetTotalPayloadTons": null,
      "paymentTermsDays": 1,
      "creditLimit": null,
      "creditLimitCurrency": null,
      "currentExposure": 1,
      "marketplaceGrade": null,
      "marketplaceScore": null,
      "totalShipmentsCompleted": 1,
      "totalVolumeTons": 1,
      "activeContractCount": 1,
      "activeLaneCount": 1,
      "memberSince": null,
      "isVerified": true,
      "isPublishedPublicly": true,
      "metadata": {},
      "verifiedAt": null,
      "verificationNotes": null,
      "isActive": true,
      "createdAt": null,
      "updatedAt": null,
      "capabilityCount": 1,
      "verifiedCapabilityCount": 1,
      "payoutAccountCount": 1,
      "verifiedPayoutCurrencies": [
        "string"
      ],
      "settlementReady": true
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/participants?page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/participants
Auth requiredparticipants.manage

Create participant

Creates a freight participant profile linked to a CRM company customer. Requires features: participants.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "customerEntityId": "00000000-0000-4000-8000-000000000000",
  "participantType": "SHIPPER",
  "nip": null,
  "regon": null,
  "krs": null,
  "vatEu": null,
  "eori": null,
  "creditLimit": null,
  "creditLimitCurrency": null,
  "marketplaceGrade": null,
  "marketplaceScore": null,
  "memberSince": null,
  "verifiedAt": null,
  "verificationNotes": null
}

Responses

201Participant created
Content-Type: application/json
{
  "id": null,
  "participantId": null
}

Example

curl -X POST "https://api.open-mercato.local/api/participants" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"customerEntityId\": \"00000000-0000-4000-8000-000000000000\",
  \"participantType\": \"SHIPPER\",
  \"nip\": null,
  \"regon\": null,
  \"krs\": null,
  \"vatEu\": null,
  \"eori\": null,
  \"creditLimit\": null,
  \"creditLimitCurrency\": null,
  \"marketplaceGrade\": null,
  \"marketplaceScore\": null,
  \"memberSince\": null,
  \"verifiedAt\": null,
  \"verificationNotes\": null
}"
PUT/api/participants
Auth requiredparticipants.manage

Update participant

Updates participant identifiers, scope summaries, or verification fields. Requires features: participants.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "nip": null,
  "regon": null,
  "krs": null,
  "vatEu": null,
  "eori": null,
  "creditLimit": null,
  "creditLimitCurrency": null,
  "marketplaceGrade": null,
  "marketplaceScore": null,
  "memberSince": null,
  "verifiedAt": null,
  "verificationNotes": null
}

Responses

200Participant updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/participants" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"nip\": null,
  \"regon\": null,
  \"krs\": null,
  \"vatEu\": null,
  \"eori\": null,
  \"creditLimit\": null,
  \"creditLimitCurrency\": null,
  \"marketplaceGrade\": null,
  \"marketplaceScore\": null,
  \"memberSince\": null,
  \"verifiedAt\": null,
  \"verificationNotes\": null
}"
DELETE/api/participants
Auth requiredparticipants.manage

Delete participant

Soft-deletes a participant profile by id. Requires features: participants.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Participant deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/participants" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/participants/{id}
Auth requiredparticipants.view

Get participant detail

Returns a participant profile with linked CRM company summary. Requires features: participants.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Participant detail payload
Content-Type: application/json
{
  "participant": {},
  "linkedCustomer": null,
  "customFields": {},
  "capabilitiesSummary": {},
  "payoutSummary": {}
}

Example

curl -X GET "https://api.open-mercato.local/api/participants/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/participants/capabilities
Auth requiredparticipants.view

List participantcapabilities

Returns a paginated collection of participantcapabilities scoped to the authenticated organization. Requires features: participants.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
participantProfileIdqueryNoany
modequeryNoany
cargoSegmentqueryNoany
equipmentTypequeryNoany
coverageCountryCodequeryNoany
coverageRegionIdqueryNoany
verificationStatusqueryNoany
pagequeryNoany
pageSizequeryNoany

Responses

200Paginated participantcapabilities
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "participantProfileId": "00000000-0000-4000-8000-000000000000",
      "mode": "string",
      "cargoSegment": "string",
      "equipmentType": "string",
      "equipmentSubtype": null,
      "capacityUnits": null,
      "maxPayloadTons": null,
      "maxWeightPerUnitTons": null,
      "coverageCountryCodes": [
        "string"
      ],
      "coverageRegionIds": [
        "00000000-0000-4000-8000-000000000000"
      ],
      "isAdrCapable": true,
      "isReeferCapable": true,
      "isOversizedCapable": true,
      "minTempC": null,
      "maxTempC": null,
      "verificationStatus": "unverified",
      "complianceDocumentId": null,
      "verifiedAt": null,
      "rejectedAt": null,
      "isActive": true,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/participants/capabilities?page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/participants/capabilities
Auth requiredparticipants.manage_capabilities

Create participantcapability

Creates a scoped participant capability record. Requires features: participants.manage_capabilities

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "participantProfileId": "00000000-0000-4000-8000-000000000000",
  "mode": "ROAD",
  "cargoSegment": "FTL",
  "equipmentType": "string",
  "equipmentSubtype": null,
  "capacityUnits": null,
  "maxPayloadTons": null,
  "maxWeightPerUnitTons": null,
  "isAdrCapable": false,
  "isReeferCapable": false,
  "isOversizedCapable": false,
  "minTempC": null,
  "maxTempC": null,
  "complianceDocumentId": null,
  "notes": null,
  "isActive": true
}

Responses

201ParticipantCapability created
Content-Type: application/json
{
  "id": null,
  "capabilityId": null
}

Example

curl -X POST "https://api.open-mercato.local/api/participants/capabilities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"participantProfileId\": \"00000000-0000-4000-8000-000000000000\",
  \"mode\": \"ROAD\",
  \"cargoSegment\": \"FTL\",
  \"equipmentType\": \"string\",
  \"equipmentSubtype\": null,
  \"capacityUnits\": null,
  \"maxPayloadTons\": null,
  \"maxWeightPerUnitTons\": null,
  \"isAdrCapable\": false,
  \"isReeferCapable\": false,
  \"isOversizedCapable\": false,
  \"minTempC\": null,
  \"maxTempC\": null,
  \"complianceDocumentId\": null,
  \"notes\": null,
  \"isActive\": true
}"
PUT/api/participants/capabilities
Auth requiredparticipants.manage_capabilities

Update participantcapability

Updates editable participant capability fields. Requires features: participants.manage_capabilities

Request body (application/json)

{
  "equipmentSubtype": null,
  "capacityUnits": null,
  "maxPayloadTons": null,
  "maxWeightPerUnitTons": null,
  "isAdrCapable": false,
  "isReeferCapable": false,
  "isOversizedCapable": false,
  "minTempC": null,
  "maxTempC": null,
  "complianceDocumentId": null,
  "notes": null,
  "isActive": true
}

Responses

200ParticipantCapability updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/participants/capabilities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"equipmentSubtype\": null,
  \"capacityUnits\": null,
  \"maxPayloadTons\": null,
  \"maxWeightPerUnitTons\": null,
  \"isAdrCapable\": false,
  \"isReeferCapable\": false,
  \"isOversizedCapable\": false,
  \"minTempC\": null,
  \"maxTempC\": null,
  \"complianceDocumentId\": null,
  \"notes\": null,
  \"isActive\": true
}"
DELETE/api/participants/capabilities
Auth requiredparticipants.manage_capabilities

Delete participantcapability

Soft-deletes a participant capability by id. Requires features: participants.manage_capabilities

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200ParticipantCapability deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/participants/capabilities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/participants/capabilities/{id}/reject
Auth requiredparticipants.verify_capabilities

Reject participant capability

Requires features: participants.verify_capabilities

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "rejectionReason": "string"
}

Responses

200Capability rejected
Content-Type: application/json
{
  "ok": true,
  "verificationStatus": "rejected"
}
404Capability was not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/participants/capabilities/:id/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"rejectionReason\": \"string\"
}"
POST/api/participants/capabilities/{id}/verify
Auth requiredparticipants.verify_capabilities

Verify participant capability

Requires features: participants.verify_capabilities

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "complianceDocumentId": null,
  "verificationNotes": null
}

Responses

200Capability verified
Content-Type: application/json
{
  "ok": true,
  "verificationStatus": "verified",
  "verifiedAt": null
}
404Capability or evidence was not found
Content-Type: application/json
"string"
409Compliance evidence is not verified or is expired
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/participants/capabilities/:id/verify" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"complianceDocumentId\": null,
  \"verificationNotes\": null
}"
GET/api/participants/eligibility
Auth requiredparticipants.view

Evaluate participant commercial eligibility

Requires features: participants.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
idsqueryNoany
participantIdsqueryNoany
modequeryNoany
cargoSegmentqueryNoany
equipmentTypequeryNoany
coverageCountryCodequeryNoany
coverageRegionIdqueryNoany
minPayloadTonsqueryNoany
requiresAdrqueryNoany
requiresReeferqueryNoany
requiresOversizedqueryNoany
payoutCurrencyqueryNoany
payoutStatusqueryNoany
settlementReadyqueryNoany
requireVerifiedCapabilityqueryNoany
requireVerifiedPayoutAccountqueryNoany

Responses

200Eligibility results returned
Content-Type: application/json
{
  "items": [
    {
      "participantId": "00000000-0000-4000-8000-000000000000",
      "eligible": true,
      "matchingCapabilityIds": [
        "00000000-0000-4000-8000-000000000000"
      ],
      "defaultPayoutAccountId": null,
      "reasons": [
        {
          "code": "string",
          "messageKey": "string"
        }
      ]
    }
  ]
}
400Invalid eligibility query
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/participants/eligibility" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/participants/lane-preferences
Auth requiredparticipants.view

List participantlanepreferences

Returns a paginated collection of participantlanepreferences scoped to the authenticated organization. Requires features: participants.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
participantProfileIdqueryNoany
laneIdqueryNoany
laneFingerprintqueryNoany
preferenceTypequeryNoany
modequeryNoany
cargoSegmentqueryNoany
isActivequeryNoany
effectiveAtqueryNoany
pagequeryNoany
pageSizequeryNoany

Responses

200Paginated participantlanepreferences
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "participantProfileId": "00000000-0000-4000-8000-000000000000",
      "laneId": null,
      "laneFingerprint": "string",
      "originLabel": "string",
      "destinationLabel": "string",
      "preferenceType": "preferred",
      "mode": null,
      "cargoSegment": null,
      "influenceScore": 1,
      "hardAvoid": true,
      "effectiveFrom": null,
      "effectiveTo": null,
      "isActive": true,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/participants/lane-preferences?page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/participants/lane-preferences
Auth requiredparticipants.manage_lane_preferences

Create participantlanepreference

Creates a participant lane preference. Requires features: participants.manage_lane_preferences

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "participantProfileId": "00000000-0000-4000-8000-000000000000",
  "laneId": null,
  "originLabel": "string",
  "destinationLabel": "string",
  "preferenceType": "preferred",
  "mode": null,
  "cargoSegment": null,
  "influenceScore": 1,
  "hardAvoid": false,
  "effectiveFrom": null,
  "effectiveTo": null,
  "internalNote": null,
  "isActive": true
}

Responses

201ParticipantLanePreference created
Content-Type: application/json
{
  "id": null,
  "preferenceId": null
}

Example

curl -X POST "https://api.open-mercato.local/api/participants/lane-preferences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"participantProfileId\": \"00000000-0000-4000-8000-000000000000\",
  \"laneId\": null,
  \"originLabel\": \"string\",
  \"destinationLabel\": \"string\",
  \"preferenceType\": \"preferred\",
  \"mode\": null,
  \"cargoSegment\": null,
  \"influenceScore\": 1,
  \"hardAvoid\": false,
  \"effectiveFrom\": null,
  \"effectiveTo\": null,
  \"internalNote\": null,
  \"isActive\": true
}"
PUT/api/participants/lane-preferences
Auth requiredparticipants.manage_lane_preferences

Update participantlanepreference

Updates a participant lane preference. Requires features: participants.manage_lane_preferences

Request body (application/json)

{
  "laneId": null,
  "mode": null,
  "cargoSegment": null,
  "hardAvoid": false,
  "effectiveFrom": null,
  "effectiveTo": null,
  "internalNote": null,
  "isActive": true
}

Responses

200ParticipantLanePreference updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/participants/lane-preferences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"laneId\": null,
  \"mode\": null,
  \"cargoSegment\": null,
  \"hardAvoid\": false,
  \"effectiveFrom\": null,
  \"effectiveTo\": null,
  \"internalNote\": null,
  \"isActive\": true
}"
DELETE/api/participants/lane-preferences
Auth requiredparticipants.manage_lane_preferences

Delete participantlanepreference

Soft-deletes a participant lane preference by id. Requires features: participants.manage_lane_preferences

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200ParticipantLanePreference deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/participants/lane-preferences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/participants/lane-preferences/{id}
Auth requiredparticipants.manage_lane_preferences

Get participant lane preference detail with encrypted note

Requires features: participants.manage_lane_preferences

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Preference returned
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "participantProfileId": "00000000-0000-4000-8000-000000000000",
  "laneId": null,
  "laneFingerprint": "string",
  "originLabel": "string",
  "destinationLabel": "string",
  "preferenceType": "preferred",
  "mode": null,
  "cargoSegment": null,
  "influenceScore": 1,
  "hardAvoid": true,
  "effectiveFrom": null,
  "effectiveTo": null,
  "isActive": true,
  "createdAt": null,
  "updatedAt": null,
  "internalNote": null
}
404Preference not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/participants/lane-preferences/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/participants/lane-preferences/{id}/history
Auth requiredparticipants.view

Get participant lane preference history

Requires features: participants.view

Parameters

NameInRequiredSchemaDescription
idpathYesany
pagequeryNoany
pageSizequeryNoany

Responses

200Preference history returned
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "eventType": "created",
      "laneFingerprint": "string",
      "changedByUserId": null,
      "changedAt": "string",
      "previousSnapshot": null,
      "nextSnapshot": null
    }
  ]
}
404Preference not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/participants/lane-preferences/:id/history?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/participants/lane-preferences/evaluate
Auth requiredparticipants.viewlanes.view

Evaluate participant lane preference and lane stats signals

Requires features: participants.view, lanes.view

Request body (application/json)

{
  "participantProfileId": "00000000-0000-4000-8000-000000000000",
  "laneId": null,
  "laneFingerprint": null,
  "cargoSegment": null
}

Responses

200Lane fit explanation returned
Content-Type: application/json
{
  "preference": {
    "participantId": "00000000-0000-4000-8000-000000000000",
    "preferenceId": null,
    "laneId": null,
    "laneFingerprint": null,
    "preferenceType": null,
    "matchedMode": null,
    "matchedCargoSegment": null,
    "influenceScore": 1,
    "hardAvoid": true,
    "reasons": [
      {
        "code": "string",
        "messageKey": "string"
      }
    ]
  },
  "stats": null,
  "explanation": [
    {
      "code": "string",
      "messageKey": "string",
      "influenceScore": 1
    }
  ]
}
400Invalid evaluation request
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/participants/lane-preferences/evaluate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"participantProfileId\": \"00000000-0000-4000-8000-000000000000\",
  \"laneId\": null,
  \"laneFingerprint\": null,
  \"cargoSegment\": null
}"
GET/api/participants/payout-accounts
Auth requiredparticipants.view

List participantpayoutaccounts

Returns a paginated collection of participantpayoutaccounts scoped to the authenticated organization. Requires features: participants.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
participantProfileIdqueryNoany
currencyqueryNoany
verificationStatusqueryNoany
isDefaultqueryNoany
pagequeryNoany
pageSizequeryNoany

Responses

200Paginated participantpayoutaccounts
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "participantProfileId": "00000000-0000-4000-8000-000000000000",
      "ibanMasked": "string",
      "ibanLast4": "string",
      "currency": "string",
      "accountHolderType": "COMPANY",
      "verificationStatus": "unverified",
      "verificationMethod": null,
      "verifiedAt": null,
      "rejectedAt": null,
      "isDefault": true,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/participants/payout-accounts?page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Compliance

Showing 6 of 6 endpoints
GET/api/compliance/documents
Auth requiredcompliance.view

List compliancedocuments

Returns a paginated collection of compliancedocuments. Requires features: compliance.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
participantProfileIdqueryNoany
documentTypequeryNoany
holderTypequeryNoany
statusqueryNoany
verificationStatusqueryNoany
validUntilBeforequeryNoany
validUntilAfterqueryNoany
sortByqueryNoany
sortOrderqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated compliancedocuments
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "participant_profile_id": "00000000-0000-4000-8000-000000000000",
      "document_type": "string",
      "document_number": "string",
      "document_name": null,
      "holder_type": "string",
      "issuer_name": null,
      "valid_from": null,
      "valid_until": null,
      "status": "string",
      "verification_status": "string",
      "insured_sum": null,
      "insured_sum_currency": null,
      "territorial_scope": null,
      "organization_id": null,
      "tenant_id": null,
      "created_at": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/compliance/documents?page=1&pageSize=25&sortBy=createdAt&sortOrder=desc" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/compliance/documents
Auth requiredcompliance.manage

Create compliancedocument

Creates a compliance document linked to a participant profile. Requires features: compliance.manage

Request body (application/json)

{
  "participantProfileId": "00000000-0000-4000-8000-000000000000",
  "documentType": "ROAD_CARRIER_AUTHORIZATION",
  "documentNumber": "string",
  "documentName": null,
  "holderType": "COMPANY",
  "holderEntityId": null,
  "holderPersonId": null,
  "holderVehicleId": null,
  "issuerName": null,
  "issuerCountry": null,
  "issuedDate": null,
  "validFrom": "2025-01-01T00:00:00.000Z",
  "validUntil": null,
  "isIndefinite": false,
  "reviewIntervalMonths": null,
  "nextReviewDate": null,
  "attachmentId": null,
  "insuredSum": null,
  "insuredSumCurrency": null,
  "insuredSumPer": null,
  "territorialScope": null,
  "insurerName": null,
  "insurerPolicyNumber": null,
  "deductibleAmount": null,
  "deductibleCurrency": null,
  "adrClasses": null,
  "dgsaAdvisorName": null,
  "dgsaCertificateNumber": null,
  "alertDaysBeforeExpiry": [
    90,
    60,
    30,
    7
  ],
  "alertSuppressed": false,
  "notes": null
}

Responses

201ComplianceDocument created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/compliance/documents" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"participantProfileId\": \"00000000-0000-4000-8000-000000000000\",
  \"documentType\": \"ROAD_CARRIER_AUTHORIZATION\",
  \"documentNumber\": \"string\",
  \"documentName\": null,
  \"holderType\": \"COMPANY\",
  \"holderEntityId\": null,
  \"holderPersonId\": null,
  \"holderVehicleId\": null,
  \"issuerName\": null,
  \"issuerCountry\": null,
  \"issuedDate\": null,
  \"validFrom\": \"2025-01-01T00:00:00.000Z\",
  \"validUntil\": null,
  \"isIndefinite\": false,
  \"reviewIntervalMonths\": null,
  \"nextReviewDate\": null,
  \"attachmentId\": null,
  \"insuredSum\": null,
  \"insuredSumCurrency\": null,
  \"insuredSumPer\": null,
  \"territorialScope\": null,
  \"insurerName\": null,
  \"insurerPolicyNumber\": null,
  \"deductibleAmount\": null,
  \"deductibleCurrency\": null,
  \"adrClasses\": null,
  \"dgsaAdvisorName\": null,
  \"dgsaCertificateNumber\": null,
  \"alertDaysBeforeExpiry\": [
    90,
    60,
    30,
    7
  ],
  \"alertSuppressed\": false,
  \"notes\": null
}"
PUT/api/compliance/documents
Auth requiredcompliance.manage

Update compliancedocument

Updates fields on a compliance document. Requires features: compliance.manage

Request body (application/json)

{
  "documentName": null,
  "holderEntityId": null,
  "holderPersonId": null,
  "holderVehicleId": null,
  "issuerName": null,
  "issuerCountry": null,
  "issuedDate": null,
  "validUntil": null,
  "isIndefinite": false,
  "reviewIntervalMonths": null,
  "nextReviewDate": null,
  "attachmentId": null,
  "insuredSum": null,
  "insuredSumCurrency": null,
  "insuredSumPer": null,
  "territorialScope": null,
  "insurerName": null,
  "insurerPolicyNumber": null,
  "deductibleAmount": null,
  "deductibleCurrency": null,
  "adrClasses": null,
  "dgsaAdvisorName": null,
  "dgsaCertificateNumber": null,
  "alertDaysBeforeExpiry": [
    90,
    60,
    30,
    7
  ],
  "alertSuppressed": false,
  "notes": null
}

Responses

200ComplianceDocument updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/compliance/documents" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"documentName\": null,
  \"holderEntityId\": null,
  \"holderPersonId\": null,
  \"holderVehicleId\": null,
  \"issuerName\": null,
  \"issuerCountry\": null,
  \"issuedDate\": null,
  \"validUntil\": null,
  \"isIndefinite\": false,
  \"reviewIntervalMonths\": null,
  \"nextReviewDate\": null,
  \"attachmentId\": null,
  \"insuredSum\": null,
  \"insuredSumCurrency\": null,
  \"insuredSumPer\": null,
  \"territorialScope\": null,
  \"insurerName\": null,
  \"insurerPolicyNumber\": null,
  \"deductibleAmount\": null,
  \"deductibleCurrency\": null,
  \"adrClasses\": null,
  \"dgsaAdvisorName\": null,
  \"dgsaCertificateNumber\": null,
  \"alertDaysBeforeExpiry\": [
    90,
    60,
    30,
    7
  ],
  \"alertSuppressed\": false,
  \"notes\": null
}"
DELETE/api/compliance/documents
Auth requiredcompliance.manage

Delete compliancedocument

Soft-deletes a compliance document by id. Requires features: compliance.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200ComplianceDocument deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/compliance/documents" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/compliance/documents/{id}/reject
Auth requiredcompliance.verify

POST /api/compliance/documents/{id}/reject

Requires features: compliance.verify

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/compliance/documents/:id/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/compliance/documents/{id}/verify
Auth requiredcompliance.verify

POST /api/compliance/documents/{id}/verify

Requires features: compliance.verify

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/compliance/documents/:id/verify" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Road

Showing 20 of 45 endpoints
GET/api/road/dispatch/assignments
Auth requireddispatch.view

List dispatchs

Lists dispatch assignments. Requires features: dispatch.view

Responses

200Paginated dispatchs
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "organizationId": "string",
      "legId": "string",
      "vehicleId": "string",
      "driverId": "string",
      "trailerId": null,
      "status": "string",
      "plannedPickupAt": null,
      "plannedDeliveryAt": null,
      "version": 1,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/road/dispatch/assignments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/dispatch/assignments
Auth requireddispatch.assign

Create dispatch

Assigns a vehicle and driver to a transport leg. Requires features: dispatch.assign

Request body (application/json)

{
  "legId": "00000000-0000-4000-8000-000000000000",
  "vehicleId": "00000000-0000-4000-8000-000000000000",
  "driverId": "00000000-0000-4000-8000-000000000000",
  "trailerId": null,
  "plannedPickupAt": null,
  "plannedDeliveryAt": null,
  "dispatcherNotes": null,
  "specialRequirements": null
}

Responses

201Dispatch created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "organizationId": "string",
  "legId": "string",
  "vehicleId": "string",
  "driverId": "string",
  "trailerId": null,
  "status": "string",
  "plannedPickupAt": null,
  "plannedDeliveryAt": null,
  "version": 1,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/road/dispatch/assignments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"legId\": \"00000000-0000-4000-8000-000000000000\",
  \"vehicleId\": \"00000000-0000-4000-8000-000000000000\",
  \"driverId\": \"00000000-0000-4000-8000-000000000000\",
  \"trailerId\": null,
  \"plannedPickupAt\": null,
  \"plannedDeliveryAt\": null,
  \"dispatcherNotes\": null,
  \"specialRequirements\": null
}"
GET/api/road/dispatch/assignments/{id}
Auth requireddispatch.view

Get dispatch assignment

Returns a single dispatch assignment. Requires features: dispatch.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Dispatch assignment returned
Content-Type: application/json
{
  "ok": true
}

Example

curl -X GET "https://api.open-mercato.local/api/road/dispatch/assignments/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/road/dispatch/assignments/{id}
Auth requireddispatch.assign

Update dispatch assignment

Updates dispatch status or reschedule. Requires features: dispatch.assign

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "plannedPickupAt": null,
  "plannedDeliveryAt": null,
  "dispatcherNotes": null,
  "specialRequirements": null,
  "version": 1
}

Responses

200Dispatch assignment updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PATCH "https://api.open-mercato.local/api/road/dispatch/assignments/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"plannedPickupAt\": null,
  \"plannedDeliveryAt\": null,
  \"dispatcherNotes\": null,
  \"specialRequirements\": null,
  \"version\": 1
}"
DELETE/api/road/dispatch/assignments/{id}
Auth requireddispatch.assign

Delete dispatch assignment

Unassigns a dispatch (soft delete). Requires features: dispatch.assign

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Dispatch assignment deleted
Content-Type: application/json
{
  "success": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/road/dispatch/assignments/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/road/dispatch/driver/orders/{id}
Auth required

Returns a single dispatch detail limited to the authenticated driver scope

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Driver dispatch detail
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "legId": "00000000-0000-4000-8000-000000000000",
  "vehicleId": "00000000-0000-4000-8000-000000000000",
  "driverId": "00000000-0000-4000-8000-000000000000",
  "trailerId": null,
  "originLocationId": null,
  "destinationLocationId": null,
  "status": "string",
  "plannedPickupAt": null,
  "plannedDeliveryAt": null,
  "actualDepartureAt": null,
  "actualPickupAt": null,
  "actualDeliveryAt": null,
  "completedAt": null,
  "dispatcherNotes": null,
  "specialRequirements": null,
  "version": 1,
  "assignedByUserId": null,
  "createdAt": "string",
  "updatedAt": "string",
  "vehiclePlate": null,
  "originLocationName": null,
  "destinationLocationName": null,
  "ecmrDocumentId": null,
  "ecmrDocumentNumber": null,
  "ecmrStatus": null,
  "isActive": true,
  "nextStatuses": [
    "string"
  ],
  "photos": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "fileName": "string",
      "mimeType": null,
      "createdAt": "string",
      "imageUrl": "string",
      "tags": [
        "string"
      ]
    }
  ]
}
403No linked driver
Content-Type: application/json
{
  "error": "string"
}
404Dispatch not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/road/dispatch/driver/orders/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/road/dispatch/driver/orders/{id}/photos
Auth required

Lists attachments for a driver-visible dispatch order

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Dispatch photos
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "fileName": "string",
      "mimeType": null,
      "createdAt": "string",
      "imageUrl": "string",
      "fileUrl": "string"
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/road/dispatch/driver/orders/:id/photos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/dispatch/driver/orders/{id}/photos
Auth required

Uploads a photo attachment for a driver-visible dispatch order

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (multipart/form-data)

file=string

Responses

201Photo uploaded
Content-Type: application/json
{
  "item": {
    "id": "00000000-0000-4000-8000-000000000000",
    "fileName": "string",
    "mimeType": null,
    "createdAt": "string",
    "imageUrl": "string",
    "fileUrl": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/road/dispatch/driver/orders/:id/photos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -d "{
  \"file\": \"string\"
}"
POST/api/road/dispatch/suggestions
Auth requireddispatch.assign

Create dispatchsuggestions

Returns available vehicles and drivers for a transport leg. Requires features: dispatch.assign

Request body (application/json)

{
  "legId": "00000000-0000-4000-8000-000000000000",
  "windowStart": null,
  "windowEnd": null
}

Responses

201DispatchSuggestions created
Content-Type: application/json
{
  "vehicles": [
    {}
  ],
  "drivers": [
    {}
  ],
  "window": {
    "start": "string",
    "end": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/road/dispatch/suggestions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"legId\": \"00000000-0000-4000-8000-000000000000\",
  \"windowStart\": null,
  \"windowEnd\": null
}"
GET/api/road/driver/active
Auth required

Returns the active dispatch assignment for the current driver.

Responses

200Active driver dispatch
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/road/driver/active" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/driver/active/manual-location
Auth required

Reports a manual GPS update for the current active dispatch.

Request body (application/json)

{
  "dispatchId": null,
  "latitude": 1,
  "longitude": 1,
  "altitudeM": null,
  "speedKmh": null,
  "headingDeg": null,
  "accuracyM": null,
  "satellites": null,
  "hdop": null,
  "recordedAt": null
}

Responses

200Manual location stored
Content-Type: application/json
{}

Example

curl -X POST "https://api.open-mercato.local/api/road/driver/active/manual-location" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"dispatchId\": null,
  \"latitude\": 1,
  \"longitude\": 1,
  \"altitudeM\": null,
  \"speedKmh\": null,
  \"headingDeg\": null,
  \"accuracyM\": null,
  \"satellites\": null,
  \"hdop\": null,
  \"recordedAt\": null
}"
GET/api/road/driver/active/photos
Auth required

Lists photos attached to the active dispatch.

Responses

200Dispatch photos
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "fileName": "string",
      "fileSize": 1,
      "mimeType": null,
      "url": "string",
      "thumbnailUrl": "string",
      "createdAt": "string"
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/road/driver/active/photos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/driver/active/photos
Auth required

Uploads a photo for the active dispatch.

Request body (multipart/form-data)

file=string

Responses

201Photo uploaded
Content-Type: application/json
{}

Example

curl -X POST "https://api.open-mercato.local/api/road/driver/active/photos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -d "{
  \"file\": \"string\"
}"
GET/api/road/driver/active/qr
Auth required

Returns the QR artifact for the active dispatch eCMR.

Responses

200Active eCMR QR
Content-Type: application/json
{}

Example

curl -X GET "https://api.open-mercato.local/api/road/driver/active/qr" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/driver/active/status
Auth required

Advances the current driver dispatch status.

Request body (application/json)

{
  "dispatchId": "00000000-0000-4000-8000-000000000000",
  "status": "ASSIGNED",
  "version": 1
}

Responses

200Driver status updated
Content-Type: application/json
{}

Example

curl -X POST "https://api.open-mercato.local/api/road/driver/active/status" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"dispatchId\": \"00000000-0000-4000-8000-000000000000\",
  \"status\": \"ASSIGNED\",
  \"version\": 1
}"
GET/api/road/driver/me
Auth required

Returns the current linked driver profile.

Responses

200Driver profile
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "firstName": "string",
  "lastName": "string",
  "phone": null,
  "email": null,
  "userId": null
}

Example

curl -X GET "https://api.open-mercato.local/api/road/driver/me" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/road/driver/orders
Auth required

Lists dispatch assignments for the current driver account.

Responses

200Driver orders
Content-Type: application/json
{
  "activeDispatchId": null,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "orderNumber": "string",
      "status": "string",
      "plannedPickupAt": null,
      "plannedDeliveryAt": null,
      "actualPickupAt": null,
      "actualDeliveryAt": null,
      "vehiclePlate": null,
      "originLabel": null,
      "destinationLabel": null,
      "attachmentCount": 1,
      "ecmr": null
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/road/driver/orders" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/road/drivers
Auth requireddrivers.view

List drivers

Returns a paginated collection of drivers scoped to the authenticated tenant and organization. Requires features: drivers.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
qqueryNoany
qualificationqueryNoany
licenseCategoryqueryNoany
isActivequeryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated drivers
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "firstName": "string",
      "lastName": "string",
      "phone": null,
      "licenseCategories": [
        "string"
      ],
      "licenseExpires": null,
      "qualifications": [
        "string"
      ],
      "adrExpires": null,
      "cpcExpires": null,
      "driverCardExpires": null,
      "isActive": true
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/road/drivers?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/drivers
Auth requireddrivers.manage

Create driver

Creates a road driver. Requires features: drivers.manage

Request body (application/json)

{
  "firstName": "string",
  "lastName": "string",
  "phone": null,
  "email": null,
  "pesel": null,
  "licenseCategories": [],
  "licenseNumber": null,
  "licenseIssuedBy": null,
  "licenseExpires": null,
  "qualifications": [],
  "adrCertificateNumber": null,
  "adrCertificateClasses": null,
  "adrExpires": null,
  "digitalTachographId": null,
  "driverCardExpires": null,
  "cpcNumber": null,
  "cpcExpires": null,
  "userId": null,
  "isActive": true
}

Responses

201Driver created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/road/drivers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"firstName\": \"string\",
  \"lastName\": \"string\",
  \"phone\": null,
  \"email\": null,
  \"pesel\": null,
  \"licenseCategories\": [],
  \"licenseNumber\": null,
  \"licenseIssuedBy\": null,
  \"licenseExpires\": null,
  \"qualifications\": [],
  \"adrCertificateNumber\": null,
  \"adrCertificateClasses\": null,
  \"adrExpires\": null,
  \"digitalTachographId\": null,
  \"driverCardExpires\": null,
  \"cpcNumber\": null,
  \"cpcExpires\": null,
  \"userId\": null,
  \"isActive\": true
}"
GET/api/road/drivers/{id}
Auth requireddrivers.view

Get driver detail

Requires features: drivers.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Driver detail
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "firstName": "string",
  "lastName": "string",
  "phone": null,
  "email": null,
  "pesel": null,
  "licenseCategories": [
    "string"
  ],
  "licenseNumber": null,
  "licenseIssuedBy": null,
  "licenseExpires": null,
  "licenseExpiresStatus": "string",
  "licenseExpiresDaysUntil": null,
  "qualifications": [
    "string"
  ],
  "adrCertificateNumber": null,
  "adrCertificateClasses": null,
  "adrExpires": null,
  "adrExpiresStatus": "string",
  "adrExpiresDaysUntil": null,
  "digitalTachographId": null,
  "driverCardExpires": null,
  "driverCardExpiresStatus": "string",
  "driverCardExpiresDaysUntil": null,
  "cpcNumber": null,
  "cpcExpires": null,
  "cpcExpiresStatus": "string",
  "cpcExpiresDaysUntil": null,
  "userId": null,
  "isActive": true,
  "createdAt": "string",
  "updatedAt": "string"
}
404Driver not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/road/drivers/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Rail Network

Showing 10 of 10 endpoints
GET/api/rail_network/proximity
Auth requiredrail_network.stations.view

Proximity search for rail stations

Find rail stations within a given radius of a geographic point using Haversine distance calculation. PostGIS-compatible. Requires features: rail_network.stations.view

Responses

200Stations within radius
Content-Type: application/json
{
  "items": [
    {
      "stationId": "00000000-0000-4000-8000-000000000000",
      "code": "string",
      "name": "string",
      "city": "string",
      "latitude": 1,
      "longitude": 1,
      "stationType": "string",
      "isElectrified": true,
      "lineNumbers": null,
      "kmMarker": null,
      "distanceKm": 1
    }
  ],
  "total": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/rail_network/proximity" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/rail_network/segments
Auth requiredrail_network.segments.view

List rail segments

Paginated list of rail segments (graph edges) with filtering by line Requires features: rail_network.segments.view

Responses

200Paginated segment list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "fromStationId": "00000000-0000-4000-8000-000000000000",
      "toStationId": "00000000-0000-4000-8000-000000000000",
      "fromStationName": null,
      "fromStationCode": null,
      "toStationName": null,
      "toStationCode": null,
      "distanceKm": 1,
      "lineNumber": "string",
      "lineCategory": "string",
      "isElectrified": true,
      "isActive": true
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/rail_network/segments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/rail_network/segments
Auth requiredrail_network.segments.manage

Create a rail segment

Create a new rail segment (graph edge) between two stations Requires features: rail_network.segments.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "fromStationId": "00000000-0000-4000-8000-000000000000",
  "toStationId": "00000000-0000-4000-8000-000000000000",
  "distanceKm": 1,
  "lineNumber": "string",
  "lineCategory": "TRUNK",
  "isElectrified": true,
  "maxSpeedKmh": null,
  "maxAxleLoadTons": null,
  "infrastructureManager": "string",
  "gaugeMm": 1435,
  "tariffZone": null,
  "source": "OSM",
  "externalId": null
}

Responses

201Segment created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/rail_network/segments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"fromStationId\": \"00000000-0000-4000-8000-000000000000\",
  \"toStationId\": \"00000000-0000-4000-8000-000000000000\",
  \"distanceKm\": 1,
  \"lineNumber\": \"string\",
  \"lineCategory\": \"TRUNK\",
  \"isElectrified\": true,
  \"maxSpeedKmh\": null,
  \"maxAxleLoadTons\": null,
  \"infrastructureManager\": \"string\",
  \"gaugeMm\": 1435,
  \"tariffZone\": null,
  \"source\": \"OSM\",
  \"externalId\": null
}"
PUT/api/rail_network/segments
Auth requiredrail_network.segments.manage

Update a rail segment

Update an existing rail segment Requires features: rail_network.segments.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "maxSpeedKmh": null,
  "maxAxleLoadTons": null,
  "gaugeMm": 1435,
  "tariffZone": null,
  "externalId": null
}

Responses

200Segment updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/rail_network/segments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"maxSpeedKmh\": null,
  \"maxAxleLoadTons\": null,
  \"gaugeMm\": 1435,
  \"tariffZone\": null,
  \"externalId\": null
}"
DELETE/api/rail_network/segments
Auth requiredrail_network.segments.manage

Delete a rail segment

Delete a rail segment Requires features: rail_network.segments.manage

Responses

200Segment deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/rail_network/segments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/rail_network/stations
Auth requiredrail_network.stations.view

List rail stations

Paginated list of rail stations with search and filtering Requires features: rail_network.stations.view

Responses

200Paginated station list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "code": "string",
      "name": "string",
      "city": "string",
      "country": "string",
      "stationType": "string",
      "latitude": 1,
      "longitude": 1,
      "isActive": true
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/rail_network/stations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/rail_network/stations
Auth requiredrail_network.stations.manage

Create a rail station

Create a new rail station with PKP/PLK codes and geographic coordinates Requires features: rail_network.stations.manage

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "code": "string",
  "name": "string",
  "nameInternational": null,
  "city": "string",
  "voivodeship": null,
  "country": "POL",
  "latitude": 1,
  "longitude": 1,
  "stationType": "FREIGHT_TERMINAL",
  "infrastructureManager": "string",
  "source": "OSM",
  "externalId": null,
  "maxTrainLengthM": null,
  "trackCount": null,
  "terminalCapacityTeu": null,
  "lineNumbers": null,
  "kmMarker": null
}

Responses

201Station created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/rail_network/stations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"code\": \"string\",
  \"name\": \"string\",
  \"nameInternational\": null,
  \"city\": \"string\",
  \"voivodeship\": null,
  \"country\": \"POL\",
  \"latitude\": 1,
  \"longitude\": 1,
  \"stationType\": \"FREIGHT_TERMINAL\",
  \"infrastructureManager\": \"string\",
  \"source\": \"OSM\",
  \"externalId\": null,
  \"maxTrainLengthM\": null,
  \"trackCount\": null,
  \"terminalCapacityTeu\": null,
  \"lineNumbers\": null,
  \"kmMarker\": null
}"
PUT/api/rail_network/stations
Auth requiredrail_network.stations.manage

Update a rail station

Update an existing rail station Requires features: rail_network.stations.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "nameInternational": null,
  "voivodeship": null,
  "country": "POL",
  "externalId": null,
  "maxTrainLengthM": null,
  "trackCount": null,
  "terminalCapacityTeu": null,
  "lineNumbers": null,
  "kmMarker": null
}

Responses

200Station updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/rail_network/stations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"nameInternational\": null,
  \"voivodeship\": null,
  \"country\": \"POL\",
  \"externalId\": null,
  \"maxTrainLengthM\": null,
  \"trackCount\": null,
  \"terminalCapacityTeu\": null,
  \"lineNumbers\": null,
  \"kmMarker\": null
}"
DELETE/api/rail_network/stations
Auth requiredrail_network.stations.manage

Delete a rail station

Soft-delete a rail station Requires features: rail_network.stations.manage

Responses

200Station deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/rail_network/stations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/rail_network/sync
Auth requiredrail_network.stations.manage

Sync rail network from external providers

Trigger rail network synchronization from UTK and/or OSM providers. Imports ~2,800 Polish stations from UTK official dataset. Requires features: rail_network.stations.manage

Request body (application/json)

{
  "provider": "all"
}

Responses

200Sync completed
Content-Type: application/json
{
  "ok": true,
  "message": "string",
  "imported": 1,
  "skipped": 1
}

Example

curl -X POST "https://api.open-mercato.local/api/rail_network/sync" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"provider\": \"all\"
}"

Train Planning

Showing 10 of 10 endpoints
GET/api/train_planning/train-plans
Auth requiredtrain_planning.view

List train plans

Paginated list of train plans with optional filtering by status or search term Requires features: train_planning.view

Responses

200Paginated train plan list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "planNumber": "string",
      "name": null,
      "status": "draft",
      "locomotiveId": "00000000-0000-4000-8000-000000000000",
      "fromStationId": null,
      "toStationId": null,
      "departureDate": null,
      "totalWeightTonnes": null,
      "totalLengthMetres": null,
      "validationErrors": null,
      "notes": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/train_planning/train-plans" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/train_planning/train-plans
Auth requiredtrain_planning.create

Create a train plan

Create a new train consist plan in draft status Requires features: train_planning.create

Request body (application/json)

{
  "planNumber": "string",
  "locomotiveId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Train plan created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/train_planning/train-plans" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"planNumber\": \"string\",
  \"locomotiveId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/train_planning/train-plans
Auth requiredtrain_planning.edit

Update a train plan

Update an existing train plan Requires features: train_planning.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Train plan updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/train_planning/train-plans" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/train_planning/train-plans
Auth requiredtrain_planning.delete

Delete a train plan

Soft-delete a train plan Requires features: train_planning.delete

Responses

200Train plan deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/train_planning/train-plans" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/train_planning/train-plans/confirm
Auth requiredtrain_planning.confirm

Confirm a train plan

Confirms a validated train plan. The plan must have passed validation before it can be confirmed. Requires features: train_planning.confirm

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Plan confirmed
Content-Type: application/json
{
  "planId": "00000000-0000-4000-8000-000000000000"
}
404Train plan not found
Content-Type: application/json
{
  "error": "string"
}
422Plan not validated or invalid input
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/train_planning/train-plans/confirm" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/train_planning/train-plans/validate
Auth requiredtrain_planning.edit

Validate train consist

Validates consist weight and length against rail network limits. Updates plan status to validated or draft depending on result. Requires features: train_planning.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Validation result
Content-Type: application/json
{
  "valid": true,
  "errors": [
    "string"
  ],
  "totals": {
    "weightTonnes": 1,
    "lengthMetres": 1
  }
}
404Train plan not found
Content-Type: application/json
{
  "error": "string"
}
422Invalid input
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/train_planning/train-plans/validate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/train_planning/train-plans/wagons
Auth requiredtrain_planning.view

List wagon slots in a train plan

Returns all wagon slots for a given train plan, ordered by position Requires features: train_planning.view

Responses

200Paginated wagon slot list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "trainPlanId": "00000000-0000-4000-8000-000000000000",
      "wagonId": "00000000-0000-4000-8000-000000000000",
      "position": 1,
      "cargoReference": null,
      "loadTonnes": null,
      "notes": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/train_planning/train-plans/wagons" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/train_planning/train-plans/wagons
Auth requiredtrain_planning.edit

Add a wagon to a train plan

Adds a wagon slot to an existing train plan consist Requires features: train_planning.edit

Request body (application/json)

{
  "trainPlanId": "00000000-0000-4000-8000-000000000000",
  "wagonId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Wagon slot added
Content-Type: application/json
{
  "slotId": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/train_planning/train-plans/wagons" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"trainPlanId\": \"00000000-0000-4000-8000-000000000000\",
  \"wagonId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/train_planning/train-plans/wagons
Auth requiredtrain_planning.edit

Update a wagon slot

Update position, cargo reference, or load for an existing wagon slot Requires features: train_planning.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Wagon slot updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/train_planning/train-plans/wagons" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/train_planning/train-plans/wagons
Auth requiredtrain_planning.edit

Remove a wagon slot

Remove a wagon from the train plan consist Requires features: train_planning.edit

Responses

200Wagon slot removed
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/train_planning/train-plans/wagons" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Terminal Scheduling

Showing 11 of 11 endpoints
GET/api/terminal_scheduling/harmonogram
Auth requiredterminal_scheduling.view

List harmonogram entries

Paginated list of harmonogram timetable entries Requires features: terminal_scheduling.view

Responses

200Paginated harmonogram list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "stationId": "00000000-0000-4000-8000-000000000000",
      "slotType": "arrival",
      "trackNumber": 1,
      "platform": null,
      "arrivalTime": "string",
      "departureTime": "string",
      "daysOfWeek": [
        1
      ],
      "validFrom": "string",
      "validUntil": null,
      "trainNumber": null,
      "isActive": true,
      "notes": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/terminal_scheduling/harmonogram" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/terminal_scheduling/harmonogram
Auth requiredterminal_scheduling.create

Create a harmonogram entry

Create a new timetable entry for regular train connections Requires features: terminal_scheduling.create

Request body (application/json)

{
  "stationId": "00000000-0000-4000-8000-000000000000",
  "slotType": "arrival",
  "trackNumber": 1,
  "arrivalTime": "string",
  "departureTime": "string",
  "daysOfWeek": [
    1
  ],
  "validFrom": "2025-01-01T00:00:00.000Z",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Harmonogram entry created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/terminal_scheduling/harmonogram" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"stationId\": \"00000000-0000-4000-8000-000000000000\",
  \"slotType\": \"arrival\",
  \"trackNumber\": 1,
  \"arrivalTime\": \"string\",
  \"departureTime\": \"string\",
  \"daysOfWeek\": [
    1
  ],
  \"validFrom\": \"2025-01-01T00:00:00.000Z\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/terminal_scheduling/harmonogram
Auth requiredterminal_scheduling.edit

Update a harmonogram entry

Update an existing harmonogram entry Requires features: terminal_scheduling.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Harmonogram entry updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/terminal_scheduling/harmonogram" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/terminal_scheduling/harmonogram
Auth requiredterminal_scheduling.delete

Delete a harmonogram entry

Soft-delete a harmonogram entry Requires features: terminal_scheduling.delete

Responses

200Harmonogram entry deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/terminal_scheduling/harmonogram" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/terminal_scheduling/harmonogram/generate
Auth requiredterminal_scheduling.create

Generate slots from harmonogram

Generate terminal slots from harmonogram timetable entries for a given date range (max 90 days) Requires features: terminal_scheduling.create

Request body (application/json)

{
  "dateFrom": "2025-01-01T00:00:00.000Z",
  "dateTo": "2025-01-01T00:00:00.000Z",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000"
}

Responses

200Slots generated
Content-Type: application/json
{
  "generated": 1
}
422Invalid input or date range
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/terminal_scheduling/harmonogram/generate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"dateFrom\": \"2025-01-01T00:00:00.000Z\",
  \"dateTo\": \"2025-01-01T00:00:00.000Z\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/terminal_scheduling/slots
Auth requiredterminal_scheduling.view

List terminal slots

Paginated list of terminal slots with optional filtering by station, type, status, track, and date range Requires features: terminal_scheduling.view

Responses

200Paginated terminal slot list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "stationId": "00000000-0000-4000-8000-000000000000",
      "slotType": "arrival",
      "status": "planned",
      "trackNumber": 1,
      "platform": null,
      "startTime": "string",
      "endTime": "string",
      "trainPlanId": null,
      "cargoDescription": null,
      "notes": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/terminal_scheduling/slots" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/terminal_scheduling/slots
Auth requiredterminal_scheduling.create

Create a terminal slot

Create a new terminal slot with conflict detection Requires features: terminal_scheduling.create

Request body (application/json)

{
  "stationId": "00000000-0000-4000-8000-000000000000",
  "slotType": "arrival",
  "trackNumber": 1,
  "startTime": "2025-01-01T00:00:00.000Z",
  "endTime": "2025-01-01T00:00:00.000Z",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Terminal slot created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
409Track conflict detected
Content-Type: application/json
{
  "error": "string",
  "conflicts": [
    {
      "id": "string",
      "startTime": "string",
      "endTime": "string"
    }
  ]
}

Example

curl -X POST "https://api.open-mercato.local/api/terminal_scheduling/slots" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"stationId\": \"00000000-0000-4000-8000-000000000000\",
  \"slotType\": \"arrival\",
  \"trackNumber\": 1,
  \"startTime\": \"2025-01-01T00:00:00.000Z\",
  \"endTime\": \"2025-01-01T00:00:00.000Z\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/terminal_scheduling/slots
Auth requiredterminal_scheduling.edit

Update a terminal slot

Update an existing terminal slot with conflict detection Requires features: terminal_scheduling.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Terminal slot updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/terminal_scheduling/slots" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/terminal_scheduling/slots
Auth requiredterminal_scheduling.delete

Delete a terminal slot

Soft-delete a terminal slot Requires features: terminal_scheduling.delete

Responses

200Terminal slot deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/terminal_scheduling/slots" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/terminal_scheduling/slots/book
Auth requiredterminal_scheduling.book

Book a terminal slot

Book a planned terminal slot, changing status to booked and triggering shunting request creation Requires features: terminal_scheduling.book

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Slot booked
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "status": "string"
}
404Slot not found
Content-Type: application/json
{
  "error": "string"
}
422Slot not in planned status
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/terminal_scheduling/slots/book" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/terminal_scheduling/slots/check-conflicts
Auth requiredterminal_scheduling.view

Check for slot conflicts

Check for overlapping track occupancy at a station without creating a slot Requires features: terminal_scheduling.view

Request body (application/json)

{
  "stationId": "00000000-0000-4000-8000-000000000000",
  "trackNumber": 1,
  "startTime": "2025-01-01T00:00:00.000Z",
  "endTime": "2025-01-01T00:00:00.000Z"
}

Responses

200Conflict check result
Content-Type: application/json
{
  "conflicts": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "startTime": "string",
      "endTime": "string"
    }
  ]
}
422Invalid input
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/terminal_scheduling/slots/check-conflicts" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"stationId\": \"00000000-0000-4000-8000-000000000000\",
  \"trackNumber\": 1,
  \"startTime\": \"2025-01-01T00:00:00.000Z\",
  \"endTime\": \"2025-01-01T00:00:00.000Z\"
}"

Rail Tracking

Showing 8 of 8 endpoints
GET/api/rail_tracking/adapters
Auth requiredrail_tracking.view

List GPS adapters

Paginated list of GPS adapters with optional filtering by type or search term Requires features: rail_tracking.view

Responses

200Paginated adapter list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "adapterType": "GBOX",
      "name": "string",
      "pollingIntervalSeconds": 1,
      "isActive": true,
      "lastPollAt": null,
      "lastError": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/rail_tracking/adapters" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/rail_tracking/adapters
Auth requiredrail_tracking.manage_adapters

Create a GPS adapter

Register a new GPS adapter for position tracking Requires features: rail_tracking.manage_adapters

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "adapterType": "GBOX",
  "name": "string",
  "config": null,
  "pollingIntervalSeconds": 60
}

Responses

201Adapter created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/rail_tracking/adapters" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"adapterType\": \"GBOX\",
  \"name\": \"string\",
  \"config\": null,
  \"pollingIntervalSeconds\": 60
}"
PUT/api/rail_tracking/adapters
Auth requiredrail_tracking.manage_adapters

Update a GPS adapter

Update an existing GPS adapter configuration Requires features: rail_tracking.manage_adapters

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "config": null,
  "pollingIntervalSeconds": 60
}

Responses

200Adapter updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/rail_tracking/adapters" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"config\": null,
  \"pollingIntervalSeconds\": 60
}"
DELETE/api/rail_tracking/adapters
Auth requiredrail_tracking.manage_adapters

Delete a GPS adapter

Soft-delete a GPS adapter Requires features: rail_tracking.manage_adapters

Responses

200Adapter deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/rail_tracking/adapters" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/rail_tracking/eta
Auth requiredrail_tracking.view

Calculate ETA to destination station

Estimates arrival time based on current position, speed, and rail network distances Requires features: rail_tracking.view

Responses

200ETA calculation result
Content-Type: application/json
{
  "locomotiveId": "00000000-0000-4000-8000-000000000000",
  "destinationStationId": "00000000-0000-4000-8000-000000000000",
  "currentPosition": {
    "latitude": 1,
    "longitude": 1,
    "speedKmh": null,
    "recordedAt": "string"
  },
  "distance": {
    "straightLineKm": 1,
    "estimatedRailKm": 1
  },
  "eta": {
    "estimatedMinutes": 1,
    "estimatedArrival": "string",
    "basedOnSpeedKmh": 1,
    "confidence": "measured"
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/rail_tracking/eta" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/rail_tracking/positions
Auth requiredrail_tracking.view

List GPS positions

Paginated list of recorded GPS positions with optional filtering Requires features: rail_tracking.view

Responses

200Paginated position list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "adapter_id": "00000000-0000-4000-8000-000000000000",
      "locomotive_id": "00000000-0000-4000-8000-000000000000",
      "latitude": 1,
      "longitude": 1,
      "speed_kmh": null,
      "heading_degrees": null,
      "altitude_m": null,
      "accuracy_m": null,
      "nearest_station_id": null,
      "recorded_at": "string",
      "received_at": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/rail_tracking/positions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/rail_tracking/positions
Auth requiredrail_tracking.record_position

Record a GPS position

Record a new GPS position for a locomotive Requires features: rail_tracking.record_position

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "adapterId": "00000000-0000-4000-8000-000000000000",
  "locomotiveId": "00000000-0000-4000-8000-000000000000",
  "latitude": 1,
  "longitude": 1,
  "speedKmh": null,
  "headingDegrees": null,
  "altitudeM": null,
  "accuracyM": null,
  "metadata": null,
  "recordedAt": "2025-01-01T00:00:00.000Z"
}

Responses

201Position recorded
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/rail_tracking/positions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"adapterId\": \"00000000-0000-4000-8000-000000000000\",
  \"locomotiveId\": \"00000000-0000-4000-8000-000000000000\",
  \"latitude\": 1,
  \"longitude\": 1,
  \"speedKmh\": null,
  \"headingDegrees\": null,
  \"altitudeM\": null,
  \"accuracyM\": null,
  \"metadata\": null,
  \"recordedAt\": \"2025-01-01T00:00:00.000Z\"
}"
GET/api/rail_tracking/positions/trail
Auth requiredrail_tracking.view

Get locomotive position trail

Returns chronological GPS position trail for a locomotive, for map replay Requires features: rail_tracking.view

Responses

200Position trail
Content-Type: application/json
{
  "locomotiveId": "00000000-0000-4000-8000-000000000000",
  "trail": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "latitude": 1,
      "longitude": 1,
      "speedKmh": null,
      "headingDegrees": null,
      "altitudeM": null,
      "accuracyM": null,
      "nearestStationId": null,
      "recordedAt": "string"
    }
  ],
  "count": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/rail_tracking/positions/trail" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Shunting

Showing 6 of 6 endpoints
GET/api/shunting/shunting-requests
Auth requiredshunting.view

List shunting requests

Paginated list of shunting requests Requires features: shunting.view

Responses

200Paginated shunting request list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "stationId": "00000000-0000-4000-8000-000000000000",
      "slotId": "00000000-0000-4000-8000-000000000000",
      "status": "pending",
      "providerId": null,
      "requestType": "string",
      "fromTrack": null,
      "toTrack": null,
      "trainPlanId": null,
      "wagons": null,
      "scheduledAt": null,
      "startedAt": null,
      "completedAt": null,
      "notes": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/shunting/shunting-requests" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/shunting/shunting-requests
Auth requiredshunting.create

Create a shunting request

Create a new shunting request for terminal maneuver Requires features: shunting.create

Request body (application/json)

{
  "stationId": "00000000-0000-4000-8000-000000000000",
  "slotId": "00000000-0000-4000-8000-000000000000",
  "requestType": "string",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Shunting request created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/shunting/shunting-requests" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"stationId\": \"00000000-0000-4000-8000-000000000000\",
  \"slotId\": \"00000000-0000-4000-8000-000000000000\",
  \"requestType\": \"string\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/shunting/shunting-requests
Auth requiredshunting.edit

Update a shunting request

Update a shunting request including status transitions Requires features: shunting.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Shunting request updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/shunting/shunting-requests" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/shunting/shunting-requests
Auth requiredshunting.delete

Delete a shunting request

Soft-delete a shunting request Requires features: shunting.delete

Responses

200Shunting request deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/shunting/shunting-requests" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/shunting/shunting-requests/complete
Auth requiredshunting.edit

Complete a shunting request

Transition shunting request from IN_PROGRESS to COMPLETED Requires features: shunting.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Shunting request completed
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "status": "string"
}
404Shunting request not found
Content-Type: application/json
{
  "error": "string"
}
422Invalid status transition
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/shunting/shunting-requests/complete" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/shunting/shunting-requests/start
Auth requiredshunting.edit

Start a shunting request

Transition shunting request from ACCEPTED to IN_PROGRESS Requires features: shunting.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Shunting request started
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "status": "string"
}
404Shunting request not found
Content-Type: application/json
{
  "error": "string"
}
422Invalid status transition
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/shunting/shunting-requests/start" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"

Rolling Stock

Showing 8 of 8 endpoints
GET/api/rolling-stock/locomotives
Auth requiredrolling_stock.view

List locomotives

Paginated list of locomotives with EVN/type/status filtering Requires features: rolling_stock.view

Responses

200Paginated locomotive list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "evn": "string",
      "name": "string",
      "series": "string",
      "vehicleType": "string",
      "status": "string",
      "weightTonnes": 1,
      "ecmName": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/rolling-stock/locomotives" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/rolling-stock/locomotives
Auth requiredrolling_stock.create

Create a locomotive

Create a new locomotive with EVN validation Requires features: rolling_stock.create

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "evn": "string",
  "name": "string",
  "series": "string",
  "vehicleType": "electric",
  "weightTonnes": 1,
  "maxSpeedKmh": null,
  "powerKw": null,
  "tractionSystems": null,
  "ecmName": "string",
  "ecmCertificateId": null,
  "ecmValidUntil": null,
  "notes": null
}

Responses

201Locomotive created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
409EVN already exists for this tenant
Content-Type: application/json
{
  "error": "string"
}
422Invalid EVN check digit
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/rolling-stock/locomotives" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"evn\": \"string\",
  \"name\": \"string\",
  \"series\": \"string\",
  \"vehicleType\": \"electric\",
  \"weightTonnes\": 1,
  \"maxSpeedKmh\": null,
  \"powerKw\": null,
  \"tractionSystems\": null,
  \"ecmName\": \"string\",
  \"ecmCertificateId\": null,
  \"ecmValidUntil\": null,
  \"notes\": null
}"
PUT/api/rolling-stock/locomotives
Auth requiredrolling_stock.edit

Update a locomotive

Update an existing locomotive Requires features: rolling_stock.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "maxSpeedKmh": null,
  "powerKw": null,
  "tractionSystems": null,
  "ecmCertificateId": null,
  "ecmValidUntil": null,
  "notes": null
}

Responses

200Locomotive updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/rolling-stock/locomotives" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"maxSpeedKmh\": null,
  \"powerKw\": null,
  \"tractionSystems\": null,
  \"ecmCertificateId\": null,
  \"ecmValidUntil\": null,
  \"notes\": null
}"
DELETE/api/rolling-stock/locomotives
Auth requiredrolling_stock.delete

Delete a locomotive

Soft-delete a locomotive Requires features: rolling_stock.delete

Responses

200Locomotive deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/rolling-stock/locomotives" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/rolling-stock/wagons
Auth requiredrolling_stock.view

List wagons

Paginated list of wagons with EVN/type/status filtering Requires features: rolling_stock.view

Responses

200Paginated wagon list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "evn": "string",
      "name": "string",
      "series": "string",
      "wagonType": "string",
      "status": "string",
      "weightTonnes": 1,
      "maxLoadTonnes": null,
      "ecmName": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/rolling-stock/wagons" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/rolling-stock/wagons
Auth requiredrolling_stock.create

Create a wagon

Create a new wagon with EVN validation Requires features: rolling_stock.create

Request body (application/json)

{
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "evn": "string",
  "name": "string",
  "series": "string",
  "wagonType": "flat",
  "weightTonnes": 1,
  "maxLoadTonnes": null,
  "lengthMetres": null,
  "capabilities": null,
  "ecmName": "string",
  "ecmCertificateId": null,
  "ecmValidUntil": null,
  "notes": null
}

Responses

201Wagon created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
409EVN already exists for this tenant
Content-Type: application/json
{
  "error": "string"
}
422Invalid EVN check digit
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/rolling-stock/wagons" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"evn\": \"string\",
  \"name\": \"string\",
  \"series\": \"string\",
  \"wagonType\": \"flat\",
  \"weightTonnes\": 1,
  \"maxLoadTonnes\": null,
  \"lengthMetres\": null,
  \"capabilities\": null,
  \"ecmName\": \"string\",
  \"ecmCertificateId\": null,
  \"ecmValidUntil\": null,
  \"notes\": null
}"
PUT/api/rolling-stock/wagons
Auth requiredrolling_stock.edit

Update a wagon

Update an existing wagon Requires features: rolling_stock.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "maxLoadTonnes": null,
  "lengthMetres": null,
  "capabilities": null,
  "ecmCertificateId": null,
  "ecmValidUntil": null,
  "notes": null
}

Responses

200Wagon updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/rolling-stock/wagons" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"maxLoadTonnes\": null,
  \"lengthMetres\": null,
  \"capabilities\": null,
  \"ecmCertificateId\": null,
  \"ecmValidUntil\": null,
  \"notes\": null
}"
DELETE/api/rolling-stock/wagons
Auth requiredrolling_stock.delete

Delete a wagon

Soft-delete a wagon Requires features: rolling_stock.delete

Responses

200Wagon deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/rolling-stock/wagons" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Example

Showing 19 of 19 endpoints
GET/api/example-customers-sync/mappings

List Example customer sync mappings

Parameters

NameInRequiredSchemaDescription
interactionIdqueryNoany
todoIdqueryNoany
limitqueryNoany
cursorqueryNoany

Responses

200Sync mappings
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "interactionId": "00000000-0000-4000-8000-000000000000",
      "todoId": "00000000-0000-4000-8000-000000000000",
      "syncStatus": "string",
      "lastSyncedAt": null,
      "lastError": null,
      "sourceUpdatedAt": null,
      "createdAt": "string",
      "updatedAt": "string",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "exampleHref": "string",
      "interaction": null
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/example-customers-sync/mappings?limit=50" \
  -H "Accept: application/json"
POST/api/example-customers-sync/reconcile

Backfill or reconcile Example todo mappings to canonical customer interactions

Request body (application/json)

{}

Responses

202Reconcile job accepted
Content-Type: application/json
{
  "queued": 1
}

Example

curl -X POST "https://api.open-mercato.local/api/example-customers-sync/reconcile" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/example/assignees
Auth requiredexample.todos.view

List example assignees

Returns mock assignee options filtered by the optional `q` query parameter. Requires features: example.todos.view

Parameters

NameInRequiredSchemaDescription
qqueryNoany

Responses

200Assignable users.
Content-Type: application/json
{
  "items": [
    {
      "value": "string",
      "label": "string"
    }
  ]
}
500Unexpected server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/example/assignees" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/example/assignees
Auth requiredexample.todos.manage

Emit SSE probe event for integration tests

Emits a clientBroadcast example todo event with optional recipient filters (user/role/org). Requires features: example.todos.manage

Responses

200Event emitted
Content-Type: application/json
{
  "ok": true,
  "eventId": "string",
  "payload": {}
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/example/assignees" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/example/blog/{id}
Auth requiredexample.todos.view

Fetch demo blog payload

Returns a placeholder blog record containing the provided identifier. Requires features: example.todos.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Placeholder blog payload.
Content-Type: application/json
{
  "id": "string",
  "method": "GET"
}

Example

curl -X GET "https://api.open-mercato.local/api/example/blog/string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/example/blog/{id}
Auth requiredexample.todos.view

Create demo blog payload

Echoes the provided identifier as a placeholder write endpoint. Requires features: example.todos.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Placeholder confirmation.
Content-Type: application/json
{
  "id": "string",
  "method": "POST"
}

Example

curl -X POST "https://api.open-mercato.local/api/example/blog/string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/example/customer-priorities
Auth requiredexample.view

List customer priorities

Returns a paginated collection of customer priorities in the current tenant scope. Requires features: example.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
customerIdqueryNoany
pagequeryNoany
pageSizequeryNoany
sortFieldqueryNoany
sortDirqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated customer priorities
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "customer_id": "00000000-0000-4000-8000-000000000000",
      "priority": "low",
      "tenant_id": null,
      "organization_id": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/example/customer-priorities?page=1&pageSize=50&sortField=created_at&sortDir=desc" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/example/customer-priorities
Auth requiredexample.todos.manage

Create customer priority

Creates or stores customer priority records for injected CRUD fields. Requires features: example.todos.manage

Request body (application/json)

{
  "customerId": "00000000-0000-4000-8000-000000000000",
  "priority": "normal"
}

Responses

201Customer Priority created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/example/customer-priorities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"customerId\": \"00000000-0000-4000-8000-000000000000\",
  \"priority\": \"normal\"
}"
PUT/api/example/customer-priorities
Auth requiredexample.todos.manage

Update customer priority

Updates customer priority values. Requires features: example.todos.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Customer Priority updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/example/customer-priorities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/example/customer-priorities
Auth requiredexample.todos.manage

Delete customer priority

Soft-deletes a customer priority record. Requires features: example.todos.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Customer Priority deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/example/customer-priorities" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/example/notifications
Auth requiredexample.todos.manage

Emit example actionable notification

Requires features: example.todos.manage

Request body (application/json)

{}

Responses

201Notification emitted
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/example/notifications" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/example/organizations
Auth requiredexample.todos.view

Resolve organization labels

Fetches organization names for the provided identifiers within the current tenant scope. Requires features: example.todos.view

Parameters

NameInRequiredSchemaDescription
idsqueryNoany

Responses

200Resolved organizations.
Content-Type: application/json
{
  "items": [
    {
      "value": "string",
      "label": "string"
    }
  ]
}
500Unexpected server error
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/example/organizations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/example/qa-events
Auth requiredexample.view

List QA-captured server events for the current tenant scope

Requires features: example.view

Responses

200Captured events
Content-Type: application/json
{
  "items": [
    {
      "event": "string",
      "payload": {},
      "capturedAt": "string"
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/example/qa-events" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/example/qa-events
Auth requiredexample.view

Clear QA-captured server events for the current tenant scope

Requires features: example.view

Responses

200Captured events cleared
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/example/qa-events" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/example/tags
Auth requiredexample.todos.view

List example tags

Returns tag options collected from custom field values and dictionary configuration. Requires features: example.todos.view

Responses

200Available tag options.
Content-Type: application/json
{
  "items": [
    {
      "value": "string",
      "label": "string"
    }
  ]
}
500Failed to resolve tags
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/example/tags" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/example/todos
Auth requiredexample.todos.view

List todos

Returns a paginated collection of todos in the current tenant scope. Requires features: example.todos.view

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
sortFieldqueryNoany
sortDirqueryNoany
titlequeryNoany
isDonequeryNoany
withDeletedqueryNoany
organizationIdqueryNoany
createdFromqueryNoany
createdToqueryNoany
formatqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).

Responses

200Paginated todos
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "title": "string",
      "tenant_id": null,
      "organization_id": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/example/todos?page=1&pageSize=50&sortField=id&sortDir=asc&withDeleted=false" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/example/todos
Auth requiredexample.todos.manage

Create todo

Creates a todo record. Supports additional custom field keys prefixed with `cf_`. Requires features: example.todos.manage

Request body (application/json)

{}

Responses

201Todo created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/example/todos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
PUT/api/example/todos
Auth requiredexample.todos.manage

Update todo

Updates an existing todo record by id. Accepts base fields and optional `cf_` custom fields. Requires features: example.todos.manage

Request body (application/json)

{}

Responses

200Todo updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/example/todos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
DELETE/api/example/todos
Auth requiredexample.todos.manage

Delete todo

Deletes a todo by id. Provide the identifier in the request body. Requires features: example.todos.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Todo deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/example/todos" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"

AI Assistant

Showing 20 of 28 endpoints
GET/api/ai_assistant/ai/actions/{id}
Auth requiredai_assistant.view

Fetch the current state of an AI pending action by id.

Returns the tenant-scoped {@link AiPendingAction} addressed by `:id`. Powers the chat UI reconnect/polling path: after a page reload or SSE reconnect the client carries the `pendingActionId` from an earlier `mutation-preview-card` UI part and calls this route to re-hydrate the card. Server-internal fields (`normalizedInput`, `createdByUserId`, `idempotencyKey`) are stripped by a whitelist serializer. Enforces tenant/org scoping via the repository. Requires features: ai_assistant.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Serialized pending action. Never includes normalizedInput, createdByUserId, or idempotencyKey.
Content-Type: application/json
"string"
404No pending action with the given id is accessible to the caller.
Content-Type: application/json
"string"
500Internal runtime failure.
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/ai_assistant/ai/actions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/ai_assistant/ai/actions/{id}/cancel
Auth requiredai_assistant.view

Cancel an AI pending action without executing the wrapped tool.

Flips a pending AI action from `pending` to `cancelled` and emits the `ai.action.cancelled` event. The tool handler is never invoked. Idempotent: a second call on a row already in `cancelled` status returns 200 with the current row without re-emitting the event. Rows whose `expiresAt` is in the past are flipped to `expired` and returned as 409 `expired` so the client can surface the TTL loss instead of silently masking it as a cancellation. Requires features: ai_assistant.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Cancellation complete (or idempotent replay); body includes the serialized pending action with status `cancelled`.
Content-Type: application/json
"string"
400Invalid cancel request body (unknown field, reason exceeds 500 chars, wrong type).
Content-Type: application/json
"string"
404Pending action not found in the caller scope.
Content-Type: application/json
"string"
409Pending action is not in `pending` status (already confirmed/failed/executing) or has expired.
Content-Type: application/json
"string"
500Unexpected server failure during cancel.
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/ai/actions/:id/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/ai_assistant/ai/actions/{id}/confirm
Auth requiredai_assistant.view

Confirm an AI pending action, re-running every server-side check before execution.

Re-verifies the full contract from spec §9.4 (status, expiry, agent registration, required features, mutation policy, tool whitelist, attachment tenant scope, record version, and schema drift), flips the pending-action state machine to `executing`, invokes the wrapped tool handler, and persists `executionResult`. Idempotent: a second call on a row already in `confirmed` state returns the prior result without re-executing the handler. Requires features: ai_assistant.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Confirmation complete; body includes the serialized pending action and the mutation result.
Content-Type: application/json
"string"
404Pending action or agent not found in the caller scope.
Content-Type: application/json
"string"
409Pending action is not in `pending` status or has expired.
Content-Type: application/json
"string"
412Record version changed between propose and confirm, or the input schema no longer accepts the stored payload.
Content-Type: application/json
"string"
500Unexpected server failure during confirm.
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/ai/actions/:id/confirm" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/ai_assistant/ai/agents
Auth requiredai_assistant.view

List registered AI agents, filtered by the caller's features.

Returns `{ agents: [...] }` — the subset of agents from `ai-agents.generated.ts` that the authenticated caller can invoke based on each agent's `requiredFeatures`. Mirrors the `meta.list_agents` tool handler so backoffice pages (e.g. the playground) can render an agent picker without going through the MCP tool transport. Requires features: ai_assistant.view

Responses

200Accessible agent summaries.
Content-Type: application/json
"string"
500Internal failure while loading the agent registry.
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/ai_assistant/ai/agents" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/ai_assistant/ai/agents/{agentId}/loop-override
Auth requiredai_assistant.view

Read the current loop-policy override for this agent, if any.

Returns `{ agentId, override }` where `override` is the agent-scoped loop-policy row from `ai_agent_runtime_overrides` (or `null`). Requires `ai_assistant.view`. Requires features: ai_assistant.view

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Responses

200Loop override payload.
Content-Type: application/json
"string"
400Invalid agent id.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/loop-override" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/ai_assistant/ai/agents/{agentId}/loop-override
Auth requiredai_assistant.settings.manage

Set (or replace) the tenant-scoped loop-policy override for this agent.

Body: loop columns. All fields are nullable/optional; `null` explicitly clears that axis. Validates `loopStopWhenJson` items and `loopActiveToolsJson` membership. Requires `ai_assistant.settings.manage`. Requires features: ai_assistant.settings.manage

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Request body (application/json)

{
  "loopDisabled": null,
  "loopMaxSteps": null,
  "loopMaxToolCalls": null,
  "loopMaxWallClockMs": null,
  "loopMaxTokens": null,
  "loopStopWhenJson": null,
  "loopActiveToolsJson": null
}

Responses

200Override persisted.
Content-Type: application/json
"string"
400Invalid agent id or validation error.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/loop-override" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"loopDisabled\": null,
  \"loopMaxSteps\": null,
  \"loopMaxToolCalls\": null,
  \"loopMaxWallClockMs\": null,
  \"loopMaxTokens\": null,
  \"loopStopWhenJson\": null,
  \"loopActiveToolsJson\": null
}"
DELETE/api/ai_assistant/ai/agents/{agentId}/loop-override
Auth requiredai_assistant.settings.manage

Remove the loop-policy columns from the agent-scoped runtime override row.

Nulls out all seven loop columns on the agent-scoped `ai_agent_runtime_overrides` row. Idempotent — returns 200 even when no override exists. Requires `ai_assistant.settings.manage`. Requires features: ai_assistant.settings.manage

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Responses

200Loop override cleared (or already absent).
Content-Type: application/json
"string"
400Invalid agent id.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X DELETE "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/loop-override" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/ai_assistant/ai/agents/{agentId}/models
Auth requiredai_assistant.view

Get the providers and curated models available for the chat-UI picker for this agent

Returns all configured providers with their curated model catalogs, filtered to providers that have an API key configured in the current environment. When the agent declares `allowRuntimeOverride: false`, the response reflects that constraint so the UI picker can hide itself. Includes the agent's resolved default provider/model so the picker can render a "(default)" badge next to the right entry. RBAC: requires the same features as the agent itself (typically `ai_assistant.view`). Requires features: ai_assistant.view

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Responses

200Providers and curated models available for the agent picker. Empty `providers` array when `allowRuntimeOverride` is false.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/models" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/ai_assistant/ai/agents/{agentId}/mutation-policy
Auth requiredai_assistant.view

Read the effective mutationPolicy for an agent — code-declared value plus any tenant override.

Returns `{ agentId, codeDeclared, override }` where `codeDeclared` is the agent's compiled-in `mutationPolicy` and `override` is the persisted tenant-scoped override (or `null`). Requires `ai_assistant.view`. Requires features: ai_assistant.view

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Responses

200Effective mutationPolicy payload.
Content-Type: application/json
"string"
400Invalid agent id.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/mutation-policy" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/ai_assistant/ai/agents/{agentId}/mutation-policy
Auth requiredai_assistant.settings.manage

Set (or replace) the tenant-scoped mutationPolicy override for this agent.

Body: `{ mutationPolicy: "read-only" | "confirm-required" | "destructive-confirm-required", notes? }`. The override MUST NOT escalate beyond the agent's code-declared policy. Escalation attempts are rejected with 400 + `code: "escalation_not_allowed"`. Requires `ai_assistant.settings.manage`. Requires features: ai_assistant.settings.manage

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Request body (application/json)

{
  "mutationPolicy": "read-only"
}

Responses

200Override persisted.
Content-Type: application/json
"string"
400Invalid agent id, malformed body, or escalation attempt.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/mutation-policy" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"mutationPolicy\": \"read-only\"
}"
DELETE/api/ai_assistant/ai/agents/{agentId}/mutation-policy
Auth requiredai_assistant.settings.manage

Remove the tenant-scoped mutationPolicy override for this agent.

Deletes the override row if it exists; subsequent calls fall back to the agent's code-declared policy. Idempotent — returns 200 even when no override exists. Requires `ai_assistant.settings.manage`. Requires features: ai_assistant.settings.manage

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Responses

200Override cleared (or already absent).
Content-Type: application/json
"string"
400Invalid agent id.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X DELETE "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/mutation-policy" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/ai_assistant/ai/agents/{agentId}/prompt-override

Read the latest prompt-section override for an agent plus recent version history.

Returns `{ agentId, override, versions }` where `override` is the latest persisted row (or `null`) and `versions` is the newest-first history capped at 10 rows. Tenant-scoped; requires `ai_assistant.settings.manage`.

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Responses

200Latest override + recent version history.
Content-Type: application/json
"string"
400Invalid agent id.
Content-Type: application/json
"string"
401Unauthenticated caller.
Content-Type: application/json
"string"
403Caller lacks `ai_assistant.settings.manage`.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/prompt-override" \
  -H "Accept: application/json"
POST/api/ai_assistant/ai/agents/{agentId}/prompt-override

Save a new prompt-section override version for the agent.

Persists an additive `{ sections: Record<sectionId, text>, notes? }` override, allocating the next monotonic version for `(tenant, org, agent)`. Reserved policy keys (`mutationPolicy`, `readOnly`, `allowedTools`, `acceptedMediaTypes`) are rejected with 400 / `reserved_key`. Requires `ai_assistant.settings.manage`.

Parameters

NameInRequiredSchemaDescription
agentIdpathYesany

Request body (application/json)

{}

Responses

200Override persisted. Returns `{ ok: true, version, updatedAt }`.
Content-Type: application/json
"string"
400Invalid agent id, malformed body, or reserved policy key.
Content-Type: application/json
"string"
401Unauthenticated caller.
Content-Type: application/json
"string"
403Caller lacks `ai_assistant.settings.manage`.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/ai/agents/:agentId/prompt-override" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/ai_assistant/ai/chat
Auth requiredai_assistant.view

Stream a chat turn for a registered AI agent

Dispatches a chat turn to the focused AI agent identified by `?agent=<module>.<agent>`. Enforces agent-level `requiredFeatures`, tool whitelisting, read-only / mutationPolicy, execution-mode compatibility, and attachment media-type policy. The streaming response body uses an AI SDK-compatible `text/event-stream` transport. Optional `?provider=`, `?model=`, and `?baseUrl=` query params let callers override the resolved provider/model/base-URL for this turn (Phase 4a). Provider must be registered and configured; baseUrl must match `AI_RUNTIME_BASEURL_ALLOWLIST` when set. Both are suppressed when the agent declares `allowRuntimeOverride: false`. Requires features: ai_assistant.view

Parameters

NameInRequiredSchemaDescription
agentqueryYesany
providerqueryNoany
modelqueryNoany
baseUrlqueryNoany
loopBudgetqueryNoany

Request body (application/json)

{
  "messages": [
    {
      "role": "user",
      "content": "string"
    }
  ]
}

Responses

200Streaming text/event-stream response compatible with AI SDK chat transports.
Content-Type: text/event-stream
string
400Invalid query param, malformed payload, or message count above the cap. Typed codes: `runtime_override_disabled` (agent has allowRuntimeOverride:false), `provider_unknown` (provider id not registered), `provider_not_configured` (provider registered but no API key in env), `baseurl_not_allowlisted` (baseUrl not in AI_RUNTIME_BASEURL_ALLOWLIST).
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"
409Agent/tool/execution-mode policy violation.
Content-Type: application/json
"string"
500Internal runtime failure.
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/ai/chat?agent=string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"messages\": [
    {
      \"role\": \"user\",
      \"content\": \"string\"
    }
  ]
}"
POST/api/ai_assistant/ai/run-object
Auth requiredai_assistant.view

Run an object-mode AI agent and return the generated object

Invokes `runAiAgentObject` server-side for the registered AI agent identified by `agent` (matching "<module>.<agent>"). Enforces the same `requiredFeatures`, tool whitelisting, mutationPolicy, and attachment media-type policy as the chat dispatcher, but additionally requires the agent to declare `executionMode: "object"`. Returns the generated object in a single JSON response (no streaming). Requires features: ai_assistant.view

Request body (application/json)

{
  "agent": "string",
  "messages": [
    {
      "role": "user",
      "content": "string"
    }
  ]
}

Responses

200Object-mode run completed; response body contains `{ object, usage?, finishReason? }`.
Content-Type: application/json
"string"
400Malformed payload or message cap exceeded.
Content-Type: application/json
"string"
404Unknown agent id.
Content-Type: application/json
"string"
409Agent/tool/execution-mode policy violation.
Content-Type: application/json
"string"
422Agent does not support object-mode execution.
Content-Type: application/json
"string"
500Internal runtime failure.
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/ai/run-object" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"agent\": \"string\",
  \"messages\": [
    {
      \"role\": \"user\",
      \"content\": \"string\"
    }
  ]
}"
POST/api/ai_assistant/chat
Auth requiredai_assistant.view

Send message to AI agent via SSE stream

Requires features: ai_assistant.view

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/chat" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/ai_assistant/health
Auth requiredai_assistant.view

Check OpenCode and MCP connection status

Requires features: ai_assistant.view

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/ai_assistant/health" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/ai_assistant/route
Auth requiredai_assistant.view

Route user query to appropriate AI handler

Requires features: ai_assistant.view

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/ai_assistant/route" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/ai_assistant/settings
Auth requiredai_assistant.view

Get AI provider configuration

Requires features: ai_assistant.view

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/ai_assistant/settings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/ai_assistant/settings
Auth requiredai_assistant.settings.manage

Upsert per-tenant AI runtime override

Creates or updates the per-tenant AI runtime override (provider, model, baseURL). Optionally scoped to a specific agent via `agentId`. Gated by `ai_assistant.settings.manage`. baseURL must match AI_RUNTIME_BASEURL_ALLOWLIST when set. Requires features: ai_assistant.settings.manage

Request body (application/json)

{
  "providerId": null,
  "modelId": null,
  "baseURL": null,
  "agentId": null,
  "allowedOverrideProviders": null
}

Responses

200Override saved. Returns the saved row.
Content-Type: application/json
"string"
400Validation error: unknown provider, invalid URL, or baseURL not allowlisted.
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/ai_assistant/settings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"providerId\": null,
  \"modelId\": null,
  \"baseURL\": null,
  \"agentId\": null,
  \"allowedOverrideProviders\": null
}"

Authentication & Accounts

Showing 20 of 23 endpoints
GET/api/auth/profile
Auth required

Get current profile

Returns the email address for the signed-in user.

Responses

200Profile payload
Content-Type: application/json
{
  "email": "[email protected]",
  "roles": [
    "string"
  ]
}
404User not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/auth/profile" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/auth/profile
Auth required

Update current profile

Updates the email address or password for the signed-in user.

Request body (application/json)

{}

Responses

200Profile updated
Content-Type: application/json
{
  "ok": true,
  "email": "[email protected]"
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/auth/profile" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/auth/roles
Auth requiredauth.roles.list

List roles

Returns available roles within the current tenant. Super administrators receive visibility across tenants. Requires features: auth.roles.list

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
tenantIdqueryNoany

Responses

200Role collection
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "usersCount": 1,
      "tenantId": null,
      "tenantName": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/auth/roles?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/auth/roles
Auth requiredauth.roles.manage

Create role

Creates a new role for the current tenant or globally when `tenantId` is omitted. Requires features: auth.roles.manage

Request body (application/json)

{
  "name": "string"
}

Responses

201Role created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/auth/roles" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\"
}"
PUT/api/auth/roles
Auth requiredauth.roles.manage

Update role

Updates mutable fields on an existing role. Requires features: auth.roles.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Role updated
Content-Type: application/json
{
  "ok": true
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Role not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/auth/roles" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/auth/roles
Auth requiredauth.roles.manage

Delete role

Deletes a role by identifier. Fails when users remain assigned. Requires features: auth.roles.manage

Parameters

NameInRequiredSchemaDescription
idqueryYesanyRole identifier

Responses

200Role deleted
Content-Type: application/json
{
  "ok": true
}
400Role cannot be deleted
Content-Type: application/json
{
  "error": "string"
}
404Role not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/auth/roles?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/auth/roles/acl
Auth requiredauth.acl.manage

Fetch role ACL

Returns the feature and organization assignments associated with a role within the current tenant. Requires features: auth.acl.manage

Parameters

NameInRequiredSchemaDescription
roleIdqueryYesany
tenantIdqueryNoany

Responses

200Role ACL entry
Content-Type: application/json
{
  "isSuperAdmin": true,
  "features": [
    "string"
  ],
  "organizations": null
}
400Invalid role id
Content-Type: application/json
{
  "error": "string"
}
404Role not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/auth/roles/acl?roleId=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/auth/roles/acl
Auth requiredauth.acl.manage

Update role ACL

Replaces the feature list, super admin flag, and optional organization assignments for a role. Requires features: auth.acl.manage

Request body (application/json)

{
  "roleId": "00000000-0000-4000-8000-000000000000",
  "organizations": null
}

Responses

200Role ACL updated
Content-Type: application/json
{
  "ok": true,
  "sanitized": true
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Role not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/auth/roles/acl" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"roleId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizations\": null
}"
GET/api/auth/sidebar/preferences
Auth required

Get sidebar preferences

Returns sidebar customization for the current user (default) or the specified role (`?roleId=…`, requires `auth.sidebar.manage`).

Responses

200Current sidebar configuration
Content-Type: application/json
{
  "locale": "string",
  "settings": {
    "version": 1,
    "groupOrder": [
      "string"
    ],
    "groupLabels": {
      "key": "string"
    },
    "itemLabels": {
      "key": "string"
    },
    "hiddenItems": [
      "string"
    ],
    "itemOrder": {
      "key": [
        "string"
      ]
    }
  },
  "canApplyToRoles": true,
  "roles": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "hasPreference": true
    }
  ],
  "scope": {
    "type": "user"
  }
}
403Missing features for role-scope read
Content-Type: application/json
{
  "error": "string"
}
404Role not found in current tenant scope
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/auth/sidebar/preferences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/auth/sidebar/preferences
Auth requiredauth.sidebar.manage

Update sidebar preferences

Updates sidebar configuration. With `scope.type === "user"` (default) writes the calling user's personal preferences and may optionally apply the same settings to selected roles via `applyToRoles[]`. With `scope.type === "role"` writes the named role variant directly (requires `auth.sidebar.manage`); `applyToRoles[]` and `clearRoleIds[]` are rejected in this mode. Requires features: auth.sidebar.manage

Request body (application/json)

{}

Responses

200Preferences saved
Content-Type: application/json
{
  "locale": "string",
  "settings": {
    "version": 1,
    "groupOrder": [
      "string"
    ],
    "groupLabels": {
      "key": "string"
    },
    "itemLabels": {
      "key": "string"
    },
    "hiddenItems": [
      "string"
    ],
    "itemOrder": {
      "key": [
        "string"
      ]
    }
  },
  "canApplyToRoles": true,
  "roles": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "hasPreference": true
    }
  ],
  "scope": {
    "type": "user"
  },
  "appliedRoles": [
    "00000000-0000-4000-8000-000000000000"
  ],
  "clearedRoles": [
    "00000000-0000-4000-8000-000000000000"
  ]
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Role not found in current tenant scope
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/auth/sidebar/preferences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
DELETE/api/auth/sidebar/preferences
Auth requiredauth.sidebar.manage

Delete a role sidebar variant

Removes the role variant for the current tenant + locale. Idempotent. Requires `auth.sidebar.manage`. Requires features: auth.sidebar.manage

Responses

200Variant deleted (or never existed)
Content-Type: application/json
{
  "ok": true,
  "scope": {
    "type": "user"
  }
}
400Missing roleId query parameter
Content-Type: application/json
{
  "error": "string"
}
404Role not found in current tenant scope
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/auth/sidebar/preferences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/auth/sidebar/variants
Auth required

List sidebar variants

Returns the named sidebar variants saved by the current user for the current tenant + locale.

Responses

200Variant list
Content-Type: application/json
{
  "locale": "string",
  "variants": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "isActive": true,
      "settings": {
        "version": 1,
        "groupOrder": [
          "string"
        ],
        "groupLabels": {
          "key": "string"
        },
        "itemLabels": {
          "key": "string"
        },
        "hiddenItems": [
          "string"
        ],
        "itemOrder": {
          "key": [
            "string"
          ]
        }
      },
      "createdAt": "string",
      "updatedAt": null
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/auth/sidebar/variants" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/auth/sidebar/variants
Auth requiredauth.sidebar.manage

Create a sidebar variant

Creates a new variant. If `name` is omitted or blank, an auto-name like "My preferences", "My preferences 2", … is assigned. Requires features: auth.sidebar.manage

Request body (application/json)

{}

Responses

200Variant created
Content-Type: application/json
{
  "locale": "string",
  "variant": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "isActive": true,
    "settings": {
      "version": 1,
      "groupOrder": [
        "string"
      ],
      "groupLabels": {
        "key": "string"
      },
      "itemLabels": {
        "key": "string"
      },
      "hiddenItems": [
        "string"
      ],
      "itemOrder": {
        "key": [
          "string"
        ]
      }
    },
    "createdAt": "string",
    "updatedAt": null
  }
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/auth/sidebar/variants" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/auth/sidebar/variants/{id}
Auth required

Get a sidebar variant

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Variant
Content-Type: application/json
{
  "locale": "string",
  "variant": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "isActive": true,
    "settings": {
      "version": 1,
      "groupOrder": [
        "string"
      ],
      "groupLabels": {
        "key": "string"
      },
      "itemLabels": {
        "key": "string"
      },
      "hiddenItems": [
        "string"
      ],
      "itemOrder": {
        "key": [
          "string"
        ]
      }
    },
    "createdAt": "string",
    "updatedAt": null
  }
}
404Variant not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/auth/sidebar/variants/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/auth/sidebar/variants/{id}
Auth requiredauth.sidebar.manage

Update a sidebar variant

Updates the variant's name, settings, and/or isActive flag. Setting `isActive: true` deactivates other variants in the same scope (only one active per user/tenant/locale). Requires features: auth.sidebar.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

200Variant updated
Content-Type: application/json
{
  "locale": "string",
  "variant": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "isActive": true,
    "settings": {
      "version": 1,
      "groupOrder": [
        "string"
      ],
      "groupLabels": {
        "key": "string"
      },
      "itemLabels": {
        "key": "string"
      },
      "hiddenItems": [
        "string"
      ],
      "itemOrder": {
        "key": [
          "string"
        ]
      }
    },
    "createdAt": "string",
    "updatedAt": null
  }
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404Variant not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/auth/sidebar/variants/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
DELETE/api/auth/sidebar/variants/{id}
Auth requiredauth.sidebar.manage

Delete a sidebar variant

Soft-deletes the variant (sets deleted_at). Requires features: auth.sidebar.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Variant deleted
Content-Type: application/json
{
  "ok": true
}
404Variant not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/auth/sidebar/variants/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/auth/users
Auth requiredauth.users.list

List users

Returns users for the current tenant. Search matches email, organization name, and role name. Super administrators may scope the response via organization or role filters. Requires features: auth.users.list

Parameters

NameInRequiredSchemaDescription
idqueryNoany
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
namequeryNoany
organizationIdqueryNoany
roleIdsqueryNoany

Responses

200User collection
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "email": "[email protected]",
      "name": null,
      "organizationId": null,
      "organizationName": null,
      "tenantId": null,
      "tenantName": null,
      "roles": [
        "string"
      ]
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/auth/users?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/auth/users
Auth requiredauth.users.create

Create user

Creates a new confirmed user within the specified organization, optional display name, and optional roles. Requires features: auth.users.create

Request body (application/json)

{
  "email": "[email protected]",
  "organizationId": "00000000-0000-4000-8000-000000000000"
}

Responses

201User created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
400Invalid payload or duplicate email
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/auth/users" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"email\": \"[email protected]\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/auth/users
Auth requiredauth.users.edit

Update user

Updates profile fields including display name, organization assignment, credentials, or role memberships. Requires features: auth.users.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200User updated
Content-Type: application/json
{
  "ok": true
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}
404User not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PUT "https://api.open-mercato.local/api/auth/users" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
DELETE/api/auth/users
Auth requiredauth.users.delete

Delete user

Deletes a user by identifier. Undo support is provided via the command bus. Requires features: auth.users.delete

Parameters

NameInRequiredSchemaDescription
idqueryYesanyUser identifier

Responses

200User deleted
Content-Type: application/json
{
  "ok": true
}
400User cannot be deleted
Content-Type: application/json
{
  "error": "string"
}
404User not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/auth/users?id=00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Rail Cargo Extensions

Showing 4 of 4 endpoints
GET/api/cim/cargo-extensions
Auth requiredcim.cargo_extensions.view

List rail cargo extensions

Paginated list of rail cargo extensions with optional filtering by cargo type, cargo ID, or search by wagon EVN/SSCC Requires features: cim.cargo_extensions.view

Responses

200Paginated rail cargo extension list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "cargoId": "00000000-0000-4000-8000-000000000000",
      "railCargoType": "CONTAINER",
      "isoContainerSize": null,
      "isoContainerTypeCode": null,
      "intermodalUnitType": null,
      "intermodalSscc": null,
      "intermodalBookingRef": null,
      "bulkMaterialCode": null,
      "bulkLoadingMethod": null,
      "bulkMoisturePercent": null,
      "bulkSpecificGravity": null,
      "wagonId": null,
      "wagonEvn": null,
      "loadingGauge": null,
      "maxAxleLoadTonnes": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/cim/cargo-extensions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/cim/cargo-extensions
Auth requiredcim.cargo_extensions.manage

Create a rail cargo extension

Create a new rail cargo extension record for a cargo item Requires features: cim.cargo_extensions.manage

Request body (application/json)

{
  "cargoId": "00000000-0000-4000-8000-000000000000",
  "isoContainerSize": null,
  "isoContainerTypeCode": null,
  "intermodalUnitType": null,
  "intermodalSscc": null,
  "intermodalBookingRef": null,
  "bulkMaterialCode": null,
  "bulkLoadingMethod": null,
  "bulkMoisturePercent": null,
  "bulkSpecificGravity": null,
  "wagonId": null,
  "wagonEvn": null,
  "loadingGauge": null,
  "maxAxleLoadTonnes": null,
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Rail cargo extension created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/cim/cargo-extensions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"cargoId\": \"00000000-0000-4000-8000-000000000000\",
  \"isoContainerSize\": null,
  \"isoContainerTypeCode\": null,
  \"intermodalUnitType\": null,
  \"intermodalSscc\": null,
  \"intermodalBookingRef\": null,
  \"bulkMaterialCode\": null,
  \"bulkLoadingMethod\": null,
  \"bulkMoisturePercent\": null,
  \"bulkSpecificGravity\": null,
  \"wagonId\": null,
  \"wagonEvn\": null,
  \"loadingGauge\": null,
  \"maxAxleLoadTonnes\": null,
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/cim/cargo-extensions
Auth requiredcim.cargo_extensions.manage

Update a rail cargo extension

Update an existing rail cargo extension Requires features: cim.cargo_extensions.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "isoContainerSize": null,
  "isoContainerTypeCode": null,
  "intermodalUnitType": null,
  "intermodalSscc": null,
  "intermodalBookingRef": null,
  "bulkMaterialCode": null,
  "bulkLoadingMethod": null,
  "bulkMoisturePercent": null,
  "bulkSpecificGravity": null,
  "wagonId": null,
  "wagonEvn": null,
  "loadingGauge": null,
  "maxAxleLoadTonnes": null
}

Responses

200Rail cargo extension updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/cim/cargo-extensions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"isoContainerSize\": null,
  \"isoContainerTypeCode\": null,
  \"intermodalUnitType\": null,
  \"intermodalSscc\": null,
  \"intermodalBookingRef\": null,
  \"bulkMaterialCode\": null,
  \"bulkLoadingMethod\": null,
  \"bulkMoisturePercent\": null,
  \"bulkSpecificGravity\": null,
  \"wagonId\": null,
  \"wagonEvn\": null,
  \"loadingGauge\": null,
  \"maxAxleLoadTonnes\": null
}"
DELETE/api/cim/cargo-extensions
Auth requiredcim.cargo_extensions.manage

Delete a rail cargo extension

Soft-delete a rail cargo extension Requires features: cim.cargo_extensions.manage

Responses

200Rail cargo extension deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/cim/cargo-extensions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

CIM Waybills

Showing 8 of 8 endpoints
GET/api/cim/waybills
Auth requiredcim.view

List CIM waybills

Paginated list of CIM waybills with optional filtering by status, waybill type, or search term Requires features: cim.view

Responses

200Paginated CIM waybill list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "waybillNumber": "string",
      "waybillType": "CIM",
      "status": "DRAFT",
      "documentId": null,
      "trainPlanId": null,
      "consignorName": "string",
      "consigneeName": "string",
      "carrierName": "string",
      "goodsDescription": "string",
      "grossWeightKg": 1,
      "isDangerous": true,
      "issuedAt": null,
      "deliveredAt": null,
      "pdfUrl": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/cim/waybills" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/cim/waybills
Auth requiredcim.create

Create a CIM waybill

Create a new CIM waybill in draft status Requires features: cim.create

Request body (application/json)

{
  "waybillNumber": "string",
  "documentId": null,
  "trainPlanId": null,
  "consignorName": "string",
  "consignorAddress": null,
  "consigneeName": "string",
  "consigneeAddress": null,
  "carrierName": "string",
  "carrierAddress": null,
  "successiveCarrierIds": null,
  "forwardingAgentName": null,
  "stationOfDepartureId": "00000000-0000-4000-8000-000000000000",
  "stationOfDestinationId": "00000000-0000-4000-8000-000000000000",
  "viaStations": null,
  "borderCrossingStations": null,
  "goodsDescription": "string",
  "nhmCode": null,
  "hsCode": null,
  "grossWeightKg": 1,
  "numberOfPackages": null,
  "packageType": null,
  "marksAndNumbers": null,
  "ridClass": null,
  "ridUnNumber": null,
  "ridPackingGroup": null,
  "ridProperShippingName": null,
  "ridTransportCategory": null,
  "ridSpecialProvisions": null,
  "ridEmergencyCard": null,
  "freightCharges": null,
  "supplementaryCharges": null,
  "remarks": null,
  "customsDeclarations": null,
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

201CIM waybill created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/cim/waybills" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"waybillNumber\": \"string\",
  \"documentId\": null,
  \"trainPlanId\": null,
  \"consignorName\": \"string\",
  \"consignorAddress\": null,
  \"consigneeName\": \"string\",
  \"consigneeAddress\": null,
  \"carrierName\": \"string\",
  \"carrierAddress\": null,
  \"successiveCarrierIds\": null,
  \"forwardingAgentName\": null,
  \"stationOfDepartureId\": \"00000000-0000-4000-8000-000000000000\",
  \"stationOfDestinationId\": \"00000000-0000-4000-8000-000000000000\",
  \"viaStations\": null,
  \"borderCrossingStations\": null,
  \"goodsDescription\": \"string\",
  \"nhmCode\": null,
  \"hsCode\": null,
  \"grossWeightKg\": 1,
  \"numberOfPackages\": null,
  \"packageType\": null,
  \"marksAndNumbers\": null,
  \"ridClass\": null,
  \"ridUnNumber\": null,
  \"ridPackingGroup\": null,
  \"ridProperShippingName\": null,
  \"ridTransportCategory\": null,
  \"ridSpecialProvisions\": null,
  \"ridEmergencyCard\": null,
  \"freightCharges\": null,
  \"supplementaryCharges\": null,
  \"remarks\": null,
  \"customsDeclarations\": null,
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/cim/waybills
Auth requiredcim.edit

Update a CIM waybill

Update an existing CIM waybill Requires features: cim.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "documentId": null,
  "trainPlanId": null,
  "consignorAddress": null,
  "consigneeAddress": null,
  "carrierAddress": null,
  "successiveCarrierIds": null,
  "forwardingAgentName": null,
  "viaStations": null,
  "borderCrossingStations": null,
  "nhmCode": null,
  "hsCode": null,
  "numberOfPackages": null,
  "packageType": null,
  "marksAndNumbers": null,
  "ridClass": null,
  "ridUnNumber": null,
  "ridPackingGroup": null,
  "ridProperShippingName": null,
  "ridTransportCategory": null,
  "ridSpecialProvisions": null,
  "ridEmergencyCard": null,
  "freightCharges": null,
  "supplementaryCharges": null,
  "remarks": null,
  "customsDeclarations": null
}

Responses

200CIM waybill updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/cim/waybills" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"documentId\": null,
  \"trainPlanId\": null,
  \"consignorAddress\": null,
  \"consigneeAddress\": null,
  \"carrierAddress\": null,
  \"successiveCarrierIds\": null,
  \"forwardingAgentName\": null,
  \"viaStations\": null,
  \"borderCrossingStations\": null,
  \"nhmCode\": null,
  \"hsCode\": null,
  \"numberOfPackages\": null,
  \"packageType\": null,
  \"marksAndNumbers\": null,
  \"ridClass\": null,
  \"ridUnNumber\": null,
  \"ridPackingGroup\": null,
  \"ridProperShippingName\": null,
  \"ridTransportCategory\": null,
  \"ridSpecialProvisions\": null,
  \"ridEmergencyCard\": null,
  \"freightCharges\": null,
  \"supplementaryCharges\": null,
  \"remarks\": null,
  \"customsDeclarations\": null
}"
DELETE/api/cim/waybills
Auth requiredcim.delete

Delete a CIM waybill

Soft-delete a CIM waybill Requires features: cim.delete

Responses

200CIM waybill deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/cim/waybills" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/cim/waybills/deliver
Auth requiredcim.edit

Deliver a CIM waybill

Transitions a CIM waybill to DELIVERED status. The waybill must be in SIGNED or IN_TRANSIT status. Sets the deliveredAt timestamp. Requires features: cim.edit

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Waybill delivered
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
404CIM waybill not found
Content-Type: application/json
{
  "error": "string"
}
422Waybill is not in signed or in-transit status, or invalid input
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/cim/waybills/deliver" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
POST/api/cim/waybills/issue
Auth requiredcim.issue

Issue a CIM waybill

Transitions a CIM waybill from DRAFT to ISSUED status. Sets the issuedAt timestamp. Requires features: cim.issue

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Waybill issued
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}
404CIM waybill not found
Content-Type: application/json
{
  "error": "string"
}
422Waybill is not in draft status or invalid input
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/cim/waybills/issue" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/cim/waybills/pdf
Auth requiredcim.view

Download CIM waybill PDF

Generates and streams a PDF for the CIM waybill. Accepts the waybill UUID via ?id= query parameter. Requires features: cim.view

Responses

200PDF file stream
Content-Type: application/json
"string"
404CIM waybill not found
Content-Type: application/json
{
  "error": "string"
}
422Invalid input
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/cim/waybills/pdf" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/cim/waybills/pdf
Auth requiredcim.view

Generate CIM waybill PDF

Generates a PDF for the CIM waybill including a QR code. Updates pdfUrl and qrCodeData on the waybill record. Requires features: cim.view

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200PDF generated
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "pdfUrl": null,
  "qrCodeData": null
}
404CIM waybill not found
Content-Type: application/json
{
  "error": "string"
}
422Invalid input
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/cim/waybills/pdf" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"

EtruckBulkSubmissions

Showing 12 of 12 endpoints
GET/api/etruck/bulk-submissions
Auth requiredetruck.bulk_submission.read

List eTruck bulk submission import batches

Requires features: etruck.bulk_submission.read

Responses

200Scoped bulk submission batches.
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/bulk-submissions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/etruck/bulk-submissions
Auth requiredetruck.bulk_submission.create

Create an eTruck bulk submission import batch

Requires features: etruck.bulk_submission.create

Request body (multipart/form-data or application/json)

string

Responses

201Created import batch.
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
"string"
413Upload too large
Content-Type: application/json
"string"
415Unsupported source media type
Content-Type: application/json
"string"
422Source parse failed
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/bulk-submissions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/etruck/bulk-submissions/{batchId}
Auth requiredetruck.bulk_submission.read

Read an eTruck bulk submission import batch

Requires features: etruck.bulk_submission.read

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany

Responses

200Import batch.
Content-Type: application/json
{}
404Batch not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/etruck/bulk-submissions/{batchId}
Auth requiredetruck.bulk_submission.resolve

Update eTruck bulk submission import mapping

Requires features: etruck.bulk_submission.resolve

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany

Request body (application/json)

{
  "mappingConfig": {}
}

Responses

200Updated import batch.
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"mappingConfig\": {}
}"
POST/api/etruck/bulk-submissions/{batchId}/archive
Auth requiredetruck.bulk_submission.archive

Archive an uncommitted eTruck bulk submission batch

Requires features: etruck.bulk_submission.archive

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany

Request body (application/json)

{}

Responses

200Archived batch.
Content-Type: application/json
"string"
409Committed rows cannot be archived
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId/archive" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/etruck/bulk-submissions/{batchId}/commit
Auth requiredetruck.bulk_submission.commitetruck.user_submission.createetruck.demand_signal.create

Commit an eTruck bulk submission batch through submission commands

Requires features: etruck.bulk_submission.commit, etruck.user_submission.create, etruck.demand_signal.create

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany

Request body (application/json)

{}

Responses

200Commit result.
Content-Type: application/json
"string"
409Batch not ready or row commit failed
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId/commit" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/etruck/bulk-submissions/{batchId}/export
Auth requiredetruck.bulk_submission.export

Export unresolved or failed eTruck bulk submission rows

Requires features: etruck.bulk_submission.export

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany
pagequeryNoany
pageSizequeryNoany
statusqueryNoany
resolutionqueryNoany
hasWarningsqueryNoany
hasErrorsqueryNoany
qqueryNoany
formatqueryNoany
includeRawqueryNoany
includeSensitivequeryNoany

Responses

200CSV or JSON export of import rows.
Content-Type: application/json
"string"
404Batch not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId/export?page=1&pageSize=100&format=csv&includeRaw=false&includeSensitive=false" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/etruck/bulk-submissions/{batchId}/rollback
Auth requiredetruck.bulk_submission.rollbacketruck.user_submission.deleteetruck.demand_signal.moderate

Rollback committed rows from an eTruck bulk submission batch

Requires features: etruck.bulk_submission.rollback, etruck.user_submission.delete, etruck.demand_signal.moderate

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany

Responses

200Rollback result.
Content-Type: application/json
"string"
409Rollback conflict
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId/rollback" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/etruck/bulk-submissions/{batchId}/rows
Auth requiredetruck.bulk_submission.read

List eTruck bulk submission rows

Requires features: etruck.bulk_submission.read

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany

Responses

200Bulk submission rows.
Content-Type: application/json
"string"
404Batch not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId/rows" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/etruck/bulk-submissions/{batchId}/rows/{rowId}/resolution
Auth requiredetruck.bulk_submission.resolve

Resolve one eTruck bulk submission row

Requires features: etruck.bulk_submission.resolve

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany
rowIdpathYesany

Request body (application/json)

{
  "resolution": "create_new"
}

Responses

200Resolved row.
Content-Type: application/json
"string"
400Validation failed
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId/rows/:rowId/resolution" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"resolution\": \"create_new\"
}"
PATCH/api/etruck/bulk-submissions/{batchId}/rows/bulk-resolution
Auth requiredetruck.bulk_submission.resolve

Bulk resolve eTruck submission rows

Requires features: etruck.bulk_submission.resolve

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany

Request body (application/json)

{
  "rowIds": [
    "00000000-0000-4000-8000-000000000000"
  ],
  "resolution": "create_new"
}

Responses

200Resolved rows.
Content-Type: application/json
"string"
400Validation failed
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId/rows/bulk-resolution" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"rowIds\": [
    \"00000000-0000-4000-8000-000000000000\"
  ],
  \"resolution\": \"create_new\"
}"
POST/api/etruck/bulk-submissions/{batchId}/validate
Auth requiredetruck.bulk_submission.validate

Validate and preview an eTruck bulk submission batch

Requires features: etruck.bulk_submission.validate

Parameters

NameInRequiredSchemaDescription
batchIdpathYesany

Responses

200Validation preview.
Content-Type: application/json
"string"
404Batch not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/bulk-submissions/:batchId/validate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

EtruckConferenceMessages

Showing 2 of 2 endpoints
GET/api/etruck/conference/messages/context
Auth requiredmessages.composeetruck.message.sendetruck.user_submission.read

List own eTruck conference message context objects

Requires features: messages.compose, etruck.message.send, etruck.user_submission.read

Parameters

NameInRequiredSchemaDescription
typequeryNoany
searchqueryNoany
pagequeryNoany
pageSizequeryNoany

Responses

200Own conference points and routes attachable to a message.
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "label": "string",
      "subtitle": null,
      "entityModule": "etruck",
      "entityType": "string",
      "entityId": "00000000-0000-4000-8000-000000000000",
      "sourceEntityType": "string",
      "sourceEntityId": "00000000-0000-4000-8000-000000000000",
      "previewData": {
        "title": "string"
      }
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "totalPages": 1
  }
}
400Validation failed
Content-Type: application/json
"string"
503Conference scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/conference/messages/context?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/etruck/conference/messages/recipients
Auth requiredmessages.composeetruck.message.send

List contactable eTruck conference message recipients

Requires features: messages.compose, etruck.message.send

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany

Responses

200Contactable conference profiles.
Content-Type: application/json
{
  "data": [
    {
      "profileId": "00000000-0000-4000-8000-000000000000",
      "userId": "00000000-0000-4000-8000-000000000000",
      "displayName": "string",
      "companyBadgeName": null,
      "jobTitle": null
    }
  ],
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "label": "string",
      "description": null,
      "profileId": "00000000-0000-4000-8000-000000000000"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 1,
    "total": 1,
    "totalPages": 1
  }
}
400Validation failed
Content-Type: application/json
"string"
503Conference scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/conference/messages/recipients?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

EtruckConference

Showing 9 of 9 endpoints
GET/api/etruck/conference/profile/me
Auth requiredetruck.conference_profile.manage_self

Read own eTruck conference profile

Requires features: etruck.conference_profile.manage_self

Responses

200Own profile.
Content-Type: application/json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "userId": "00000000-0000-4000-8000-000000000000",
    "publicSlug": "string",
    "companyBadgeName": null,
    "jobTitle": null,
    "publicDisplayMode": "string",
    "registrationStatus": "string",
    "registeredAt": "string",
    "activatedAt": null,
    "withdrawnAt": null,
    "consents": {
      "messages": true,
      "publicProfile": true,
      "shareCompanyBadge": true
    }
  }
}
404Profile not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/conference/profile/me" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/etruck/conference/profile/me
Auth requiredetruck.conference_profile.manage_self

Update own eTruck conference profile

Requires features: etruck.conference_profile.manage_self

Request body (application/json)

{
  "companyBadgeName": null,
  "jobTitle": null
}

Responses

200Updated profile.
Content-Type: application/json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "userId": "00000000-0000-4000-8000-000000000000",
    "publicSlug": "string",
    "companyBadgeName": null,
    "jobTitle": null,
    "publicDisplayMode": "string",
    "registrationStatus": "string",
    "registeredAt": "string",
    "activatedAt": null,
    "withdrawnAt": null,
    "consents": {
      "messages": true,
      "publicProfile": true,
      "shareCompanyBadge": true
    }
  }
}
400Validation failed
Content-Type: application/json
"string"
404Profile not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/etruck/conference/profile/me" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"companyBadgeName\": null,
  \"jobTitle\": null
}"
POST/api/etruck/conference/profile/me/withdraw
Auth requiredetruck.conference_profile.manage_self

Withdraw own eTruck conference profile

Requires features: etruck.conference_profile.manage_self

Responses

200Withdrawn profile.
Content-Type: application/json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "registrationStatus": "withdrawn"
  }
}
404Profile not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/conference/profile/me/withdraw" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/etruck/conference/profiles
Auth requiredetruck.conference_profile.manage

List eTruck conference profiles

Requires features: etruck.conference_profile.manage

Responses

200Conference profiles.
Content-Type: application/json
{
  "data": [
    {}
  ],
  "meta": {
    "page": 1,
    "pageSize": 1,
    "total": 1
  }
}
400Validation failed
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/conference/profiles" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/etruck/conference/profiles/{id}
Auth requiredetruck.conference_profile.manage

Update an eTruck conference profile

Requires features: etruck.conference_profile.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "companyBadgeName": null,
  "jobTitle": null
}

Responses

200Updated profile.
Content-Type: application/json
{
  "data": {}
}
400Validation failed
Content-Type: application/json
"string"
404Profile not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/etruck/conference/profiles/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"companyBadgeName\": null,
  \"jobTitle\": null
}"
DELETE/api/etruck/conference/profiles/{id}
Auth requiredetruck.conference_profile.manage

Soft-delete an eTruck conference profile

Requires features: etruck.conference_profile.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Deleted profile.
Content-Type: application/json
{
  "data": {}
}
404Profile not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"

Example

curl -X DELETE "https://api.open-mercato.local/api/etruck/conference/profiles/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/etruck/conference/profiles/public

List public-safe eTruck conference profiles

Responses

200Public conference profiles.
Content-Type: application/json
{
  "items": [
    {
      "publicSlug": "string",
      "displayName": "string",
      "companyBadgeName": null,
      "jobTitle": null,
      "displayMode": "string",
      "contactAvailable": true
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1
}
400Validation failed
Content-Type: application/json
"string"
429Rate limited
Content-Type: application/json
"string"
503Conference scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/conference/profiles/public" \
  -H "Accept: application/json"
POST/api/etruck/conference/registrations

Request an eTruck conference registration link

Request body (application/json)

"string"

Responses

202Registration request accepted.
Content-Type: application/json
{
  "ok": true,
  "data": {
    "status": "accepted",
    "expiresAt": "string",
    "emailSent": true
  }
}
400Validation failed
Content-Type: application/json
"string"
404Registration disabled
Content-Type: application/json
"string"
409Email already registered
Content-Type: application/json
"string"
429Rate limited
Content-Type: application/json
"string"
503Conference scope unavailable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/conference/registrations" \
  -H "Accept: application/json"
POST/api/etruck/conference/registrations/activate

Activate an eTruck conference registration

Request body (application/json)

{
  "token": "string"
}

Responses

202Activation accepted.
Content-Type: application/json
{
  "ok": true,
  "data": {
    "status": "accepted"
  }
}
400Invalid or expired token
Content-Type: application/json
"string"
429Rate limited
Content-Type: application/json
"string"
503Conference scope unavailable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/conference/registrations/activate" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"token\": \"string\"
}"

etruck-public

Showing 15 of 15 endpoints
GET/api/etruck/data/download/{dataset}

Public dataset download (CC-BY-SA-4.0)

Downloads a full dataset for the configured public scope. Path segment is "{slug}.{format}" — slug ∈ charging-points|grid-connections|road-flows|business-pois|mismatch|grid-substations|grid-capacity-gmina|oze-installations|ten-t-corridors|grid-feasibility; format ∈ geojson|csv|parquet (parquet falls back to CSV when not available, marked via X-Format-Fallback header).

Parameters

NameInRequiredSchemaDescription
datasetpathYesany

Responses

200Encoded dataset stream with CC-BY-SA-4.0 license headers
Content-Type: application/json
"string"
404Unknown dataset or format
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/data/download/:dataset" \
  -H "Accept: application/json"
GET/api/etruck/grid/capacity-gmina

Public eTruck gmina grid capacity aggregates

Returns public-safe gmina-level grid capacity aggregates for the configured public scope.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
wojewodztwoqueryNoany
gridOperatorCodequeryNoany
yearqueryNoany
minAvailableMwqueryNoany
pageSizequeryNoany

Responses

200JSON rows
Content-Type: application/json
[
  {}
]
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/grid/capacity-gmina?pageSize=100" \
  -H "Accept: application/json"
GET/api/etruck/grid/feasibility

Public eTruck grid charging feasibility

Returns gmina-level grid charging feasibility rows joined with gmina metadata for map rendering.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
wojewodztwoqueryNoany
gridOperatorCodequeryNoany
yearqueryNoany
minScorequeryNoany
maxScorequeryNoany
pageSizequeryNoany

Responses

200JSON rows
Content-Type: application/json
[
  {}
]
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/grid/feasibility?pageSize=100" \
  -H "Accept: application/json"
GET/api/etruck/grid/feasibility/{gminaTeryt}

Public eTruck grid charging feasibility drill-down

Returns a single public-safe gmina feasibility row for the configured public scope.

Parameters

NameInRequiredSchemaDescription
gminaTerytpathYesany

Responses

200JSON row
Content-Type: application/json
{}
400Invalid route parameter
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/grid/feasibility/string" \
  -H "Accept: application/json"
GET/api/etruck/grid/oze-installations

Public eTruck OZE installations

Returns public-safe OZE installation points for the configured public scope.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
sourceTypequeryNoany
statusqueryNoany
dataSourcequeryNoany
minCapacityKwqueryNoany
nearCorridorqueryNoany
pageSizequeryNoany

Responses

200GeoJSON FeatureCollection
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "key": "string"
      }
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/grid/oze-installations?pageSize=100" \
  -H "Accept: application/json"
GET/api/etruck/grid/substations

Public eTruck grid substations

Returns public-safe grid substation points for the configured public scope.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
gridOperatorCodequeryNoany
gminaTerytqueryNoany
minCapacityMwqueryNoany
congestionqueryNoany
pageSizequeryNoany

Responses

200GeoJSON FeatureCollection
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "key": "string"
      }
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/grid/substations?pageSize=100" \
  -H "Accept: application/json"
GET/api/etruck/grid/ten-t-corridors

Public eTruck TEN-T corridors

Returns current TEN-T corridor lines without buffer geometry by default.

Parameters

NameInRequiredSchemaDescription
pageSizequeryNoany

Responses

200GeoJSON FeatureCollection
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "key": "string"
      }
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/grid/ten-t-corridors?pageSize=1000" \
  -H "Accept: application/json"
GET/api/etruck/reports/glec-summary

GLEC v3.2 baseline summary for a lane (no DB write)

Computes a road-only baseline. Without v3.2 inputs (vehicleSegment, loadPct, gridMixRegion), falls back to Etap A legacy formula and returns methodology="GLEC_V3_LEGACY". With v3.2 inputs, routes to SFC GLEC Framework v3.2 (October 2025) Module 2 Table 8/9 + Module 1 Table p.77-78 fuel WTW factors, and returns methodology="GLEC_V3_2". Pure function delegation — does not persist EmissionReport.

Parameters

NameInRequiredSchemaDescription
lanequeryYesany
fuelTypequeryYesany
euroClassqueryNoany
freightTonnesqueryNoany
vehicleSegmentqueryNoany
loadPctqueryNoany
loadBucketqueryNoany
gridMixRegionqueryNoany

Responses

200GLEC summary
Content-Type: application/json
{
  "gCO2ePerTkm": 1,
  "methodology": "GLEC_V3_2",
  "factorKey": "string",
  "totalKgCo2e": 1,
  "freightTonneKm": 1,
  "sources": [
    "string"
  ]
}
400Invalid query or lane
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/reports/glec-summary?lane=string&fuelType=DIESEL&freightTonnes=20" \
  -H "Accept: application/json"
GET/api/etruck/reports/mismatch

Public mismatch signals report

Returns active MismatchSignal records as GeoJSON FeatureCollection with public-only evidence allow-list.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
severityqueryNoany

Responses

200GeoJSON FeatureCollection
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "key": "string"
      }
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/reports/mismatch" \
  -H "Accept: application/json"
GET/api/etruck/reports/public-summary

Public aggregate summary (Hero stats)

Returns aggregated chargers count, subsidies total (PLN), and mismatches counts within the configured public scope. No authentication required. Used by the public portal Hero Stat Strip.

Responses

200Aggregate summary
Content-Type: application/json
{
  "chargersTotal": 1,
  "subsidiesPlnTotal": 1,
  "mismatchesTotal": 1,
  "highMismatchesTotal": 1,
  "generatedAt": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/reports/public-summary" \
  -H "Accept: application/json"
GET/api/etruck/visibility/business-pois

Public business points of interest (visibility layer)

Returns DCs, intermodal terminals, manufacturing sites, ports, carrier bases for the configured public scope.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
categoryqueryNoany

Responses

200GeoJSON FeatureCollection
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "key": "string"
      }
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/visibility/business-pois" \
  -H "Accept: application/json"
GET/api/etruck/visibility/charging-points

Public charging points (visibility layer)

Returns operational, planned and decommissioned charging points within the configured public scope. No authentication required.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
statusqueryNoany
sourceTypequeryNoany

Responses

200GeoJSON FeatureCollection
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "key": "string"
      }
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/visibility/charging-points" \
  -H "Accept: application/json"
GET/api/etruck/visibility/grid-connections

Public grid connections (visibility layer)

Returns DSO grid connection capacities within the configured public scope.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
dsoCodequeryNoany

Responses

200GeoJSON FeatureCollection
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "key": "string"
      }
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/visibility/grid-connections" \
  -H "Accept: application/json"
GET/api/etruck/visibility/public-subsidy-attributions

Public subsidy attributions (visibility layer)

Returns awarded grants (FENIKS, KPO, CEF, NFOS_OWN, NCBR, PFR, OTHER) for the configured public scope. JSON array (not GeoJSON).

Parameters

NameInRequiredSchemaDescription
programmequeryNoany
yearqueryNoany

Responses

200JSON array of subsidy attributions
Content-Type: application/json
[
  {
    "id": "00000000-0000-4000-8000-000000000000",
    "programme": "string",
    "grantId": "string",
    "beneficiaryExternalId": "string",
    "awardedPln": null,
    "awardedEur": null,
    "awardedAt": "string",
    "subjectCategory": "string",
    "subjectExternalId": "string",
    "year": 1
  }
]
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/visibility/public-subsidy-attributions" \
  -H "Accept: application/json"
GET/api/etruck/visibility/road-flows

Public road freight flows (visibility layer)

Returns HDV count per day per road segment for the configured public scope. Geometry uses centroid Point.

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
min-hdv-per-dayqueryNoany

Responses

200GeoJSON FeatureCollection
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "key": "string"
      }
    }
  ]
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
429Rate limit exceeded
Content-Type: application/json
{
  "error": "string"
}
500Internal error
Content-Type: application/json
{
  "error": "string"
}
503Public dataset is not configured
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/etruck/visibility/road-flows" \
  -H "Accept: application/json"

EtruckDemandSignals

Showing 5 of 5 endpoints
POST/api/etruck/demand-signals
Auth requiredetruck.demand_signal.create

Create or reactivate an eTruck conference demand signal

Requires features: etruck.demand_signal.create

Request body (application/json)

{
  "targetKind": "user_submission",
  "targetEntityId": "00000000-0000-4000-8000-000000000000",
  "signalKind": "need_charging",
  "publicDisplayMode": "anonymous",
  "comment": null
}

Responses

201Demand summary after upsert.
Content-Type: application/json
{
  "data": {
    "targetKind": "string",
    "targetEntityId": "00000000-0000-4000-8000-000000000000",
    "signalKind": "string",
    "activeCount": 1,
    "anonymousCount": 1,
    "ownActive": true,
    "ownSignalId": null
  }
}
400Validation failed
Content-Type: application/json
"string"
404Demand target not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/demand-signals" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"targetKind\": \"user_submission\",
  \"targetEntityId\": \"00000000-0000-4000-8000-000000000000\",
  \"signalKind\": \"need_charging\",
  \"publicDisplayMode\": \"anonymous\",
  \"comment\": null
}"
PATCH/api/etruck/demand-signals/{id}/moderation
Auth requiredetruck.demand_signal.moderate

Moderate an eTruck conference demand signal

Requires features: etruck.demand_signal.moderate

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "moderationStatus": "active",
  "moderationReason": null
}

Responses

200Demand summary after moderation.
Content-Type: application/json
{
  "data": {
    "targetKind": "string",
    "targetEntityId": "00000000-0000-4000-8000-000000000000",
    "signalKind": "string",
    "activeCount": 1,
    "anonymousCount": 1,
    "ownActive": true,
    "ownSignalId": null
  }
}
400Validation failed
Content-Type: application/json
"string"
404Demand signal not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/etruck/demand-signals/:id/moderation" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"moderationStatus\": \"active\",
  \"moderationReason\": null
}"
GET/api/etruck/demand-signals/geojson

Read public eTruck conference demand aggregates as GeoJSON

Parameters

NameInRequiredSchemaDescription
bboxqueryNoany
targetKindqueryNoany
signalKindqueryNoany
minDemandCountqueryNoany
pageSizequeryNoany

Responses

200Public demand aggregate GeoJSON.
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {}
  ]
}
400Validation failed
Content-Type: application/json
"string"
429Rate limited
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/demand-signals/geojson?pageSize=100" \
  -H "Accept: application/json"
DELETE/api/etruck/demand-signals/me
Auth requiredetruck.demand_signal.delete_own

Withdraw the current user demand signal

Requires features: etruck.demand_signal.delete_own

Parameters

NameInRequiredSchemaDescription
targetKindqueryYesany
targetEntityIdqueryYesany
signalKindqueryNoany

Responses

200Demand summary after withdrawal.
Content-Type: application/json
{
  "data": {
    "targetKind": "string",
    "targetEntityId": "00000000-0000-4000-8000-000000000000",
    "signalKind": "string",
    "activeCount": 1,
    "anonymousCount": 1,
    "ownActive": true,
    "ownSignalId": null
  }
}
400Validation failed
Content-Type: application/json
"string"
404Demand target not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X DELETE "https://api.open-mercato.local/api/etruck/demand-signals/me?targetKind=user_submission&targetEntityId=00000000-0000-4000-8000-000000000000&signalKind=need_charging" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/etruck/demand-signals/summary

Read demand aggregate summary for a target

Parameters

NameInRequiredSchemaDescription
targetKindqueryYesany
targetEntityIdqueryYesany
signalKindqueryNoany

Responses

200Demand summary.
Content-Type: application/json
{
  "data": {
    "targetKind": "string",
    "targetEntityId": "00000000-0000-4000-8000-000000000000",
    "signalKind": "string",
    "activeCount": 1,
    "anonymousCount": 1,
    "ownActive": true,
    "ownSignalId": null
  }
}
400Validation failed
Content-Type: application/json
"string"
404Demand target not found
Content-Type: application/json
"string"
429Rate limited
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/demand-signals/summary?targetKind=user_submission&targetEntityId=00000000-0000-4000-8000-000000000000&signalKind=need_charging" \
  -H "Accept: application/json"

EtruckGeocoding

Showing 1 of 1 endpoints

EtruckRouting

Showing 1 of 1 endpoints
POST/api/etruck/routing/route
Auth requiredetruck.routing.route

Preview eTruck route geometry through the configured backend routing provider

Requires features: etruck.routing.route

Request body (application/json)

{
  "profile": "truck",
  "origin": {
    "latitude": 1,
    "longitude": 1
  },
  "destination": {
    "latitude": 1,
    "longitude": 1
  },
  "waypoints": []
}

Responses

200Normalized LineString route geometry.
Content-Type: application/json
{
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [
        1,
        1
      ]
    ]
  },
  "provider": "none",
  "profile": "truck",
  "distanceMeters": null,
  "durationSeconds": null,
  "fallback": true
}
400Validation failed
Content-Type: application/json
"string"
429Routing rate limit exceeded
Content-Type: application/json
"string"
503Routing provider unavailable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/routing/route" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"profile\": \"truck\",
  \"origin\": {
    \"latitude\": 1,
    \"longitude\": 1
  },
  \"destination\": {
    \"latitude\": 1,
    \"longitude\": 1
  },
  \"waypoints\": []
}"

EtruckUserSubmissions

Showing 7 of 7 endpoints
GET/api/etruck/user-submissions
Auth requiredetruck.user_submission.read

List eTruck conference point and route submissions

Requires features: etruck.user_submission.read

Responses

200Scoped point submissions.
Content-Type: application/json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "submissionType": "string",
      "status": "string",
      "visibility": "string",
      "publicDisplayMode": "string",
      "title": "string",
      "description": null,
      "category": "string",
      "latitude": null,
      "longitude": null,
      "origin": null,
      "destination": null,
      "routeGeometry": null,
      "demandCount": 1,
      "ownedByCurrentUser": true,
      "canModerate": true,
      "updatedByUserId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 1,
    "total": 1
  }
}
400Validation failed
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/user-submissions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/etruck/user-submissions
Auth requiredetruck.user_submission.create

Create an eTruck conference point or route submission

Requires features: etruck.user_submission.create

Request body (application/json)

{
  "title": "string",
  "description": null,
  "category": "route_stop",
  "origin": {
    "latitude": 1,
    "longitude": 1
  },
  "destination": {
    "latitude": 1,
    "longitude": 1
  },
  "waypoints": [],
  "routeGeometry": {
    "type": "LineString",
    "coordinates": [
      [
        1,
        1
      ]
    ]
  },
  "routingProvider": null,
  "routingProfile": null,
  "distanceMeters": null,
  "durationSeconds": null,
  "visibility": "private",
  "publicDisplayMode": "anonymous",
  "metadata": {},
  "submissionType": "route"
}

Responses

201Created submission.
Content-Type: application/json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "submissionType": "string",
    "status": "string",
    "visibility": "string",
    "publicDisplayMode": "string",
    "title": "string",
    "description": null,
    "category": "string",
    "latitude": null,
    "longitude": null,
    "origin": null,
    "destination": null,
    "routeGeometry": null,
    "demandCount": 1,
    "ownedByCurrentUser": true,
    "canModerate": true,
    "updatedByUserId": null,
    "createdAt": "string",
    "updatedAt": "string"
  }
}
400Validation failed
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/etruck/user-submissions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"title\": \"string\",
  \"description\": null,
  \"category\": \"route_stop\",
  \"origin\": {
    \"latitude\": 1,
    \"longitude\": 1
  },
  \"destination\": {
    \"latitude\": 1,
    \"longitude\": 1
  },
  \"waypoints\": [],
  \"routeGeometry\": {
    \"type\": \"LineString\",
    \"coordinates\": [
      [
        1,
        1
      ]
    ]
  },
  \"routingProvider\": null,
  \"routingProfile\": null,
  \"distanceMeters\": null,
  \"durationSeconds\": null,
  \"visibility\": \"private\",
  \"publicDisplayMode\": \"anonymous\",
  \"metadata\": {},
  \"submissionType\": \"route\"
}"
GET/api/etruck/user-submissions/{id}
Auth requiredetruck.user_submission.read

Read an eTruck conference point or route submission

Requires features: etruck.user_submission.read

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Submission detail.
Content-Type: application/json
{
  "data": {}
}
404Submission not found
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/user-submissions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/etruck/user-submissions/{id}
Auth requiredetruck.user_submission.update

Update an eTruck conference point or route submission

Requires features: etruck.user_submission.update

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "description": null,
  "category": "route_stop",
  "waypoints": [],
  "routingProvider": null,
  "routingProfile": null,
  "distanceMeters": null,
  "durationSeconds": null,
  "visibility": "private",
  "publicDisplayMode": "anonymous",
  "metadata": {}
}

Responses

200Updated submission.
Content-Type: application/json
{
  "data": {}
}
400Validation failed
Content-Type: application/json
"string"
404Submission not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/etruck/user-submissions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"description\": null,
  \"category\": \"route_stop\",
  \"waypoints\": [],
  \"routingProvider\": null,
  \"routingProfile\": null,
  \"distanceMeters\": null,
  \"durationSeconds\": null,
  \"visibility\": \"private\",
  \"publicDisplayMode\": \"anonymous\",
  \"metadata\": {}
}"
DELETE/api/etruck/user-submissions/{id}
Auth requiredetruck.user_submission.delete

Soft-delete an eTruck conference point or route submission

Requires features: etruck.user_submission.delete

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Deleted submission.
Content-Type: application/json
{
  "data": {}
}
404Submission not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X DELETE "https://api.open-mercato.local/api/etruck/user-submissions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/etruck/user-submissions/{id}/moderation
Auth requiredetruck.user_submission.moderate

Moderate an eTruck conference point submission

Requires features: etruck.user_submission.moderate

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "status": "pending",
  "moderationReason": null
}

Responses

200Moderated point submission.
Content-Type: application/json
{
  "data": {}
}
400Validation failed
Content-Type: application/json
"string"
404Submission not found
Content-Type: application/json
"string"
409Mutation guard conflict
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/etruck/user-submissions/:id/moderation" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"status\": \"pending\",
  \"moderationReason\": null
}"
GET/api/etruck/user-submissions/geojson

Read public eTruck conference point or route submissions as GeoJSON

Responses

200Public point submissions GeoJSON.
Content-Type: application/json
{
  "type": "FeatureCollection",
  "features": [
    {}
  ]
}
400Validation failed
Content-Type: application/json
"string"
429Rate limited
Content-Type: application/json
"string"
503Submission scope unavailable
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/etruck/user-submissions/geojson" \
  -H "Accept: application/json"

EtruckSubmissionLinks

Showing 2 of 2 endpoints

Freight Billing

Showing 5 of 5 endpoints
GET/api/freight/billing/invoices
Auth requiredbilling.view

List freight invoices

Requires features: billing.view

Responses

200Paginated freight invoice list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "invoiceNumber": "string",
      "status": "string",
      "transportMode": "string",
      "dispatchId": null,
      "legId": null,
      "cargoId": null,
      "issuerName": "string",
      "recipientName": "string",
      "issueDate": null,
      "serviceDate": null,
      "dueDate": "string",
      "currencyCode": "string",
      "vatRate": 1,
      "netAmount": 1,
      "vatAmount": 1,
      "grossAmount": 1,
      "paymentTermsDays": 1,
      "paymentReference": null,
      "notes": null,
      "ksefReference": null,
      "ksefSubmittedAt": null,
      "metadata": null,
      "createdAt": "string",
      "updatedAt": "string",
      "lineItems": [],
      "organizationId": "string",
      "tenantId": "string",
      "transportDocumentId": null,
      "issuerEntityId": null,
      "recipientEntityId": null,
      "issuerNip": null,
      "recipientNip": null,
      "ksefPayload": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/billing/invoices" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/billing/invoices/{id}
Auth requiredbilling.view

Get freight invoice

Requires features: billing.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Invoice detail
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "organizationId": "string",
  "tenantId": "string",
  "invoiceNumber": "string",
  "status": "string",
  "transportMode": "string",
  "dispatchId": null,
  "legId": null,
  "cargoId": null,
  "transportDocumentId": null,
  "issuerEntityId": null,
  "recipientEntityId": null,
  "issuerName": "string",
  "issuerNip": null,
  "recipientName": "string",
  "recipientNip": null,
  "issueDate": null,
  "serviceDate": null,
  "dueDate": "string",
  "currencyCode": "string",
  "vatRate": 1,
  "netAmount": 1,
  "vatAmount": 1,
  "grossAmount": 1,
  "paymentTermsDays": 1,
  "paymentReference": null,
  "notes": null,
  "ksefPayload": null,
  "ksefReference": null,
  "ksefSubmittedAt": null,
  "metadata": null,
  "createdAt": "string",
  "updatedAt": "string",
  "lineItems": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "lineNumber": 1,
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "currencyCode": "string",
      "unitPriceNet": 1,
      "netAmount": 1,
      "vatRate": 1,
      "vatAmount": 1,
      "grossAmount": 1,
      "serviceContext": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/billing/invoices/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/freight/billing/invoices/{id}
Auth requiredbilling.manage

Delete freight invoice

Requires features: billing.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Invoice deleted
Content-Type: application/json
{
  "success": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/freight/billing/invoices/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/billing/invoices/{id}/finalize
Auth requiredbilling.manage

Finalize invoice

Requires features: billing.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Invoice finalized
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "status": "ISSUED"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/billing/invoices/:id/finalize" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/billing/invoices/from-dispatch
Auth requiredbilling.manage

Create invoice from completed dispatch

Requires features: billing.manage

Request body (application/json)

{
  "dispatchId": "00000000-0000-4000-8000-000000000000",
  "cargoId": null,
  "transportDocumentId": null,
  "transportMode": "ROAD",
  "issuerEntityId": null,
  "recipientEntityId": null,
  "issuerName": "string",
  "recipientName": "string",
  "serviceDate": null,
  "dueDate": null,
  "currencyCode": "string",
  "vatRate": 23,
  "paymentTermsDays": 30,
  "paymentReference": null,
  "notes": null,
  "lineItems": [
    {
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceNet": 1,
      "serviceContext": null
    }
  ],
  "metadata": null
}

Responses

201Invoice created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/billing/invoices/from-dispatch" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"dispatchId\": \"00000000-0000-4000-8000-000000000000\",
  \"cargoId\": null,
  \"transportDocumentId\": null,
  \"transportMode\": \"ROAD\",
  \"issuerEntityId\": null,
  \"recipientEntityId\": null,
  \"issuerName\": \"string\",
  \"recipientName\": \"string\",
  \"serviceDate\": null,
  \"dueDate\": null,
  \"currencyCode\": \"string\",
  \"vatRate\": 23,
  \"paymentTermsDays\": 30,
  \"paymentReference\": null,
  \"notes\": null,
  \"lineItems\": [
    {
      \"description\": \"string\",
      \"quantity\": 1,
      \"unit\": \"string\",
      \"unitPriceNet\": 1,
      \"serviceContext\": null
    }
  ],
  \"metadata\": null
}"

Freight Cargo

Showing 7 of 7 endpoints
GET/api/freight/cargo
Auth requiredcargo.view

List cargo

Requires features: cargo.view

Responses

200Paginated cargo list
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "cargoType": "string",
      "referenceNumber": "string",
      "currentMode": null,
      "lastEventAt": null,
      "assignments": [
        {
          "id": "string",
          "cargoId": null,
          "salesShipmentId": null,
          "executionReferenceKind": null,
          "executionReferenceId": null,
          "relationship": "string",
          "notes": null,
          "createdAt": null,
          "updatedAt": null
        }
      ]
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/cargo" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/cargo
Auth requiredcargo.create

Register cargo

Requires features: cargo.create

Request body (application/json)

{
  "tenantId": "string",
  "organizationId": "string",
  "cargoType": "container",
  "referenceNumber": "string",
  "description": null,
  "containerNumber": null,
  "containerSizeType": null,
  "sealNumber": null,
  "gs1Sscc": null,
  "palletCount": null,
  "palletType": null,
  "bulkMaterial": null,
  "bulkUnit": null,
  "bulkQuantity": null,
  "weightKg": null,
  "volumeM3": null,
  "packageCount": null,
  "isDangerous": false,
  "dangerousGoodsUnNumber": null,
  "dangerousGoodsClass": null,
  "dangerousGoodsPackingGroup": null,
  "dangerousGoodsNotes": null,
  "requiresTempControl": false,
  "tempMinC": null,
  "tempMaxC": null,
  "currentLocation": null,
  "currentMode": null,
  "lastEventAt": null,
  "metadata": null,
  "assignments": []
}

Responses

201Cargo created
Content-Type: application/json
{
  "id": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/cargo" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"string\",
  \"organizationId\": \"string\",
  \"cargoType\": \"container\",
  \"referenceNumber\": \"string\",
  \"description\": null,
  \"containerNumber\": null,
  \"containerSizeType\": null,
  \"sealNumber\": null,
  \"gs1Sscc\": null,
  \"palletCount\": null,
  \"palletType\": null,
  \"bulkMaterial\": null,
  \"bulkUnit\": null,
  \"bulkQuantity\": null,
  \"weightKg\": null,
  \"volumeM3\": null,
  \"packageCount\": null,
  \"isDangerous\": false,
  \"dangerousGoodsUnNumber\": null,
  \"dangerousGoodsClass\": null,
  \"dangerousGoodsPackingGroup\": null,
  \"dangerousGoodsNotes\": null,
  \"requiresTempControl\": false,
  \"tempMinC\": null,
  \"tempMaxC\": null,
  \"currentLocation\": null,
  \"currentMode\": null,
  \"lastEventAt\": null,
  \"metadata\": null,
  \"assignments\": []
}"
GET/api/freight/cargo/{id}
Auth requiredcargo.view

Get cargo detail

Requires features: cargo.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Cargo detail returned
Content-Type: application/json
"string"
404Cargo not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/cargo/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PUT/api/freight/cargo/{id}
Auth requiredcargo.update

Update cargo

Requires features: cargo.update

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "cargoType": "container",
  "referenceNumber": "string",
  "description": null,
  "containerNumber": null,
  "containerSizeType": null,
  "sealNumber": null,
  "gs1Sscc": null,
  "palletCount": null,
  "palletType": null,
  "bulkMaterial": null,
  "bulkUnit": null,
  "bulkQuantity": null,
  "weightKg": null,
  "volumeM3": null,
  "packageCount": null,
  "isDangerous": false,
  "dangerousGoodsUnNumber": null,
  "dangerousGoodsClass": null,
  "dangerousGoodsPackingGroup": null,
  "dangerousGoodsNotes": null,
  "requiresTempControl": false,
  "tempMinC": null,
  "tempMaxC": null,
  "currentLocation": null,
  "currentMode": null,
  "lastEventAt": null,
  "metadata": null,
  "assignments": []
}

Responses

200Cargo updated
Content-Type: application/json
{
  "id": "string"
}
404Cargo not found
Content-Type: application/json
"string"

Example

curl -X PUT "https://api.open-mercato.local/api/freight/cargo/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"cargoType\": \"container\",
  \"referenceNumber\": \"string\",
  \"description\": null,
  \"containerNumber\": null,
  \"containerSizeType\": null,
  \"sealNumber\": null,
  \"gs1Sscc\": null,
  \"palletCount\": null,
  \"palletType\": null,
  \"bulkMaterial\": null,
  \"bulkUnit\": null,
  \"bulkQuantity\": null,
  \"weightKg\": null,
  \"volumeM3\": null,
  \"packageCount\": null,
  \"isDangerous\": false,
  \"dangerousGoodsUnNumber\": null,
  \"dangerousGoodsClass\": null,
  \"dangerousGoodsPackingGroup\": null,
  \"dangerousGoodsNotes\": null,
  \"requiresTempControl\": false,
  \"tempMinC\": null,
  \"tempMaxC\": null,
  \"currentLocation\": null,
  \"currentMode\": null,
  \"lastEventAt\": null,
  \"metadata\": null,
  \"assignments\": []
}"
DELETE/api/freight/cargo/{id}
Auth requiredcargo.delete

Delete cargo

Requires features: cargo.delete

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Cargo deleted
Content-Type: application/json
{
  "ok": true
}
404Cargo not found
Content-Type: application/json
"string"

Example

curl -X DELETE "https://api.open-mercato.local/api/freight/cargo/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/cargo/{id}/history
Auth requiredcargo.view

List cargo history

Requires features: cargo.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Paginated cargo history
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "cargoId": null,
      "eventType": "string",
      "mode": null,
      "happenedAt": null,
      "source": null,
      "notes": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/cargo/:id/history" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/freight/cargo/{id}/location
Auth requiredcargo.update

Update cargo location

Requires features: cargo.update

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "currentLocation": null,
  "currentMode": null,
  "lastEventAt": null,
  "source": null,
  "notes": null
}

Responses

200Cargo live state updated
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/freight/cargo/:id/location" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"currentLocation\": null,
  \"currentMode\": null,
  \"lastEventAt\": null,
  \"source\": null,
  \"notes\": null
}"

Freight Disputes

Showing 16 of 16 endpoints
GET/api/freight/disputes/cases
Auth requireddisputes.view

List dispute cases

Requires features: disputes.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
searchqueryNoany
statusqueryNoany
categoryqueryNoany
priorityqueryNoany
slaStatusqueryNoany
settlementHoldStatusqueryNoany
carrierParticipantIdqueryNoany
settlementEntryIdqueryNoany
marketplaceShipmentIdqueryNoany
fromqueryNoany
toqueryNoany
includeSensitivequeryNoany

Responses

200Dispute cases returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "caseNumber": "string",
      "status": "draft",
      "category": "damage",
      "priority": "low",
      "sourceSettlementEntryId": "string",
      "sourcePayoutRequestId": null,
      "sourceSettlementRunId": null,
      "sourceMarketplaceShipmentId": null,
      "sourceMarketplaceProposalId": null,
      "sourcePricingEstimateId": null,
      "carrierParticipantId": null,
      "carrierOrganizationId": null,
      "currency": null,
      "claimedAmount": null,
      "settlementEntryAmount": null,
      "title": "string",
      "assignedUserId": null,
      "openedByUserId": null,
      "openedAt": null,
      "dueAt": null,
      "slaStatus": "not_started",
      "settlementHoldStatus": "not_started",
      "settlementHoldAppliedAt": null,
      "payoutHoldStatus": null,
      "payoutHoldAppliedAt": null,
      "outcome": null,
      "severity": null,
      "feedbackDirection": null,
      "reputationFeedbackStatus": "not_applicable",
      "resolvedByUserId": null,
      "resolvedAt": null,
      "reopenCount": 1,
      "revision": 1,
      "isActive": true,
      "createdAt": "string",
      "updatedAt": "string",
      "claimSummary": null,
      "internalNotes": null,
      "decisionNote": null
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1,
  "nextCursor": null
}
400Invalid query
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/disputes/cases?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/disputes/cases
Auth requireddisputes.create

Create dispute case

Requires features: disputes.create

Request body (application/json)

{
  "settlementEntryId": "string",
  "category": "damage",
  "priority": "normal",
  "title": "string",
  "claimSummary": null,
  "internalNotes": null,
  "claimedAmount": null,
  "currency": null,
  "assignedUserId": null
}

Responses

201Dispute case created
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}
400Invalid request
Content-Type: application/json
"string"
409Active dispute already exists
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"settlementEntryId\": \"string\",
  \"category\": \"damage\",
  \"priority\": \"normal\",
  \"title\": \"string\",
  \"claimSummary\": null,
  \"internalNotes\": null,
  \"claimedAmount\": null,
  \"currency\": null,
  \"assignedUserId\": null
}"
GET/api/freight/disputes/cases/{id}
Auth requireddisputes.view

Get dispute case

Requires features: disputes.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Dispute case returned
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "caseNumber": "string",
  "status": "draft",
  "category": "damage",
  "priority": "low",
  "sourceSettlementEntryId": "string",
  "sourcePayoutRequestId": null,
  "sourceSettlementRunId": null,
  "sourceMarketplaceShipmentId": null,
  "sourceMarketplaceProposalId": null,
  "sourcePricingEstimateId": null,
  "carrierParticipantId": null,
  "carrierOrganizationId": null,
  "currency": null,
  "claimedAmount": null,
  "settlementEntryAmount": null,
  "title": "string",
  "assignedUserId": null,
  "openedByUserId": null,
  "openedAt": null,
  "dueAt": null,
  "slaStatus": "not_started",
  "settlementHoldStatus": "not_started",
  "settlementHoldAppliedAt": null,
  "payoutHoldStatus": null,
  "payoutHoldAppliedAt": null,
  "outcome": null,
  "severity": null,
  "feedbackDirection": null,
  "reputationFeedbackStatus": "not_applicable",
  "resolvedByUserId": null,
  "resolvedAt": null,
  "reopenCount": 1,
  "revision": 1,
  "isActive": true,
  "createdAt": "string",
  "updatedAt": "string",
  "claimSummary": null,
  "internalNotes": null,
  "decisionNote": null
}
404Dispute case not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/disputes/cases/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/freight/disputes/cases/{id}
Auth requireddisputes.manage

Update dispute case

Requires features: disputes.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "assignedUserId": null,
  "internalNotes": null
}

Responses

200Dispute case updated
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}
409Revision conflict
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/freight/disputes/cases/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"assignedUserId\": null,
  \"internalNotes\": null
}"
DELETE/api/freight/disputes/cases/{id}
Auth requireddisputes.manage

Delete dispute case

Requires features: disputes.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

200Dispute case deleted
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}

Example

curl -X DELETE "https://api.open-mercato.local/api/freight/disputes/cases/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/freight/disputes/cases/{id}/assign
Auth requireddisputes.manage

Assign dispute case

Requires features: disputes.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "assignedUserId": null
}

Responses

200Dispute case assigned
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases/:id/assign" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"assignedUserId\": null
}"
POST/api/freight/disputes/cases/{id}/cancel
Auth requireddisputes.manage

Cancel dispute case

Requires features: disputes.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Dispute case cancelled
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases/:id/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
POST/api/freight/disputes/cases/{id}/evidence
Auth requireddisputes.evidence

Add dispute evidence

Requires features: disputes.evidence

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "evidenceType": "pod",
  "status": "submitted",
  "sourceModule": null,
  "sourceEntityType": null,
  "sourceEntityId": null,
  "attachmentIds": [],
  "summary": null,
  "sensitivePayload": null,
  "receivedFromParty": null,
  "observedAt": null
}

Responses

200Dispute evidence added
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "disputeCaseId": "string",
    "evidenceType": "pod",
    "status": "submitted",
    "sourceModule": null,
    "sourceEntityType": null,
    "sourceEntityId": null,
    "summary": null,
    "sensitivePayload": null,
    "submittedByUserId": null,
    "receivedFromParty": null,
    "observedAt": null,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases/:id/evidence" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"evidenceType\": \"pod\",
  \"status\": \"submitted\",
  \"sourceModule\": null,
  \"sourceEntityType\": null,
  \"sourceEntityId\": null,
  \"attachmentIds\": [],
  \"summary\": null,
  \"sensitivePayload\": null,
  \"receivedFromParty\": null,
  \"observedAt\": null
}"
POST/api/freight/disputes/cases/{id}/open
Auth requireddisputes.managedisputes.settlement_hold

Open dispute case

Requires features: disputes.manage, disputes.settlement_hold

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

200Dispute case opened
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases/:id/open" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/freight/disputes/cases/{id}/reject
Auth requireddisputes.manage

Reject dispute case

Requires features: disputes.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "outcome": "insufficient_evidence",
  "severity": "neutral",
  "feedbackDirection": "none",
  "decisionNote": null
}

Responses

200Dispute case rejected
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases/:id/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"outcome\": \"insufficient_evidence\",
  \"severity\": \"neutral\",
  \"feedbackDirection\": \"none\",
  \"decisionNote\": null
}"
POST/api/freight/disputes/cases/{id}/reopen
Auth requireddisputes.managedisputes.settlement_hold

Reopen dispute case

Requires features: disputes.manage, disputes.settlement_hold

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Dispute case reopened
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases/:id/reopen" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
POST/api/freight/disputes/cases/{id}/request-evidence
Auth requireddisputes.manage

Request dispute evidence

Requires features: disputes.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null,
  "dueAt": null
}

Responses

200Evidence requested
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases/:id/request-evidence" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null,
  \"dueAt\": null
}"
POST/api/freight/disputes/cases/{id}/resolve
Auth requireddisputes.managedisputes.settlement_hold

Resolve dispute case

Requires features: disputes.manage, disputes.settlement_hold

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "outcome": "carrier_responsible",
  "severity": "neutral",
  "settlementAction": "keep_held",
  "feedbackDirection": "neutral",
  "acceptedAmount": null,
  "decisionNote": null
}

Responses

200Dispute case resolved
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "caseNumber": "string",
    "status": "draft",
    "category": "damage",
    "priority": "low",
    "sourceSettlementEntryId": "string",
    "sourcePayoutRequestId": null,
    "sourceSettlementRunId": null,
    "sourceMarketplaceShipmentId": null,
    "sourceMarketplaceProposalId": null,
    "sourcePricingEstimateId": null,
    "carrierParticipantId": null,
    "carrierOrganizationId": null,
    "currency": null,
    "claimedAmount": null,
    "settlementEntryAmount": null,
    "title": "string",
    "assignedUserId": null,
    "openedByUserId": null,
    "openedAt": null,
    "dueAt": null,
    "slaStatus": "not_started",
    "settlementHoldStatus": "not_started",
    "settlementHoldAppliedAt": null,
    "payoutHoldStatus": null,
    "payoutHoldAppliedAt": null,
    "outcome": null,
    "severity": null,
    "feedbackDirection": null,
    "reputationFeedbackStatus": "not_applicable",
    "resolvedByUserId": null,
    "resolvedAt": null,
    "reopenCount": 1,
    "revision": 1,
    "isActive": true,
    "createdAt": "string",
    "updatedAt": "string",
    "claimSummary": null,
    "internalNotes": null,
    "decisionNote": null
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/cases/:id/resolve" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"outcome\": \"carrier_responsible\",
  \"severity\": \"neutral\",
  \"settlementAction\": \"keep_held\",
  \"feedbackDirection\": \"neutral\",
  \"acceptedAmount\": null,
  \"decisionNote\": null
}"
GET/api/freight/disputes/evidence
Auth requireddisputes.view

List dispute evidence

Requires features: disputes.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
caseIdqueryNoany
evidenceTypequeryNoany
statusqueryNoany
includeSensitivequeryNoany

Responses

200Dispute evidence returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "disputeCaseId": "string",
      "evidenceType": "pod",
      "status": "submitted",
      "sourceModule": null,
      "sourceEntityType": null,
      "sourceEntityId": null,
      "summary": null,
      "sensitivePayload": null,
      "submittedByUserId": null,
      "receivedFromParty": null,
      "observedAt": null,
      "revision": 1,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1,
  "nextCursor": null
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/disputes/evidence?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/disputes/sla
Auth requireddisputes.view

List dispute SLA checkpoints

Requires features: disputes.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
caseIdqueryNoany
statusqueryNoany
checkpointTypequeryNoany
overdueOnlyqueryNoany

Responses

200Dispute SLA checkpoints returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "disputeCaseId": "string",
      "checkpointType": "first_action",
      "status": "pending",
      "dueAt": "string",
      "completedAt": null,
      "breachedAt": null,
      "escalatedAt": null,
      "ownerUserId": null,
      "escalationUserId": null,
      "calculationMode": "calendar_time",
      "pauseReason": null,
      "idempotencyKey": "string",
      "revision": 1,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1,
  "nextCursor": null
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/disputes/sla?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/disputes/sla/scan
Auth requireddisputes.admin

Start dispute SLA scan

Requires features: disputes.admin

Request body (application/json)

{
  "dryRun": false
}

Responses

202Dispute SLA scan queued
Content-Type: application/json
{
  "ok": true,
  "progressJobId": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/disputes/sla/scan" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"dryRun\": false
}"

Freight Documents

Showing 5 of 5 endpoints
GET/api/freight/documents
Auth requireddocuments.view

List transport documents

Returns a paginated list of transport documents scoped to the current organization. Requires features: documents.view

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/documents" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/documents
Auth requireddocuments.create

Create transport document

Creates a new transport document in DRAFT status. Requires features: documents.create

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/documents" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/documents/{id}
Auth requireddocuments.view

Get transport document

Returns a single transport document by ID. Requires features: documents.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/documents/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/freight/documents/{id}
Auth requireddocuments.manage

Update transport document

Updates a transport document. Only allowed in DRAFT or ISSUED status. Requires features: documents.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Success response
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/freight/documents/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/documents/{id}/sign
Auth requireddocuments.sign

Sign transport document

Appends a signature record and advances document status. Requires features: documents.sign

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

201Success response
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/documents/:id/sign" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Freight Emissions

Showing 3 of 3 endpoints
GET/api/freight/emissions
Auth requiredemissions.view

List freight emission reports

Requires features: emissions.view

Responses

200Paginated emission reports.
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "dispatchId": null,
      "legId": null,
      "vehicleId": null,
      "cargoId": null,
      "routeId": null,
      "transportDocumentId": null,
      "period": "string",
      "transportMode": "string",
      "calculationMode": "string",
      "roadKm": 1,
      "railKm": 1,
      "freightWeightKg": 1,
      "freightTonneKm": 1,
      "roadCo2Kg": 1,
      "railCo2Kg": 1,
      "totalCo2Kg": 1,
      "alternativeRoadOnlyCo2Kg": 1,
      "co2SavedKg": 1,
      "co2SavedPct": 1,
      "methodology": "string",
      "vehicleEuroClass": null,
      "fuelType": null,
      "appliedFactorKgPerTkm": 1,
      "factorKey": "string",
      "calculationTrace": null,
      "generatedAt": "string",
      "createdAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/emissions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/emissions/{id}
Auth requiredemissions.view

Get freight emission report detail

Requires features: emissions.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Emission report detail.
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "dispatchId": null,
  "legId": null,
  "vehicleId": null,
  "cargoId": null,
  "routeId": null,
  "transportDocumentId": null,
  "period": "string",
  "transportMode": "string",
  "calculationMode": "string",
  "roadKm": 1,
  "railKm": 1,
  "freightWeightKg": 1,
  "freightTonneKm": 1,
  "roadCo2Kg": 1,
  "railCo2Kg": 1,
  "totalCo2Kg": 1,
  "alternativeRoadOnlyCo2Kg": 1,
  "co2SavedKg": 1,
  "co2SavedPct": 1,
  "methodology": "string",
  "vehicleEuroClass": null,
  "fuelType": null,
  "appliedFactorKgPerTkm": 1,
  "factorKey": "string",
  "calculationTrace": null,
  "generatedAt": "string",
  "createdAt": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/emissions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/emissions/calculate
Auth requiredemissions.manage

Calculate and persist a freight emission report

Requires features: emissions.manage

Request body (application/json)

{
  "dispatchId": null,
  "legId": null,
  "vehicleId": null,
  "cargoId": null,
  "routeId": null,
  "transportDocumentId": null,
  "distanceKm": null,
  "freightWeightKg": null,
  "vehicleEuroClass": null,
  "fuelType": null,
  "calculationMode": "PLANNED",
  "vehicleSegment": null,
  "loadPct": null,
  "loadBucket": null,
  "emptyKmShare": null,
  "gridMixRegion": null
}

Responses

201Calculated emission report.
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "dispatchId": null,
  "legId": null,
  "vehicleId": null,
  "cargoId": null,
  "routeId": null,
  "transportDocumentId": null,
  "period": "string",
  "transportMode": "string",
  "calculationMode": "string",
  "roadKm": 1,
  "railKm": 1,
  "freightWeightKg": 1,
  "freightTonneKm": 1,
  "roadCo2Kg": 1,
  "railCo2Kg": 1,
  "totalCo2Kg": 1,
  "alternativeRoadOnlyCo2Kg": 1,
  "co2SavedKg": 1,
  "co2SavedPct": 1,
  "methodology": "string",
  "vehicleEuroClass": null,
  "fuelType": null,
  "appliedFactorKgPerTkm": 1,
  "factorKey": "string",
  "calculationTrace": null,
  "generatedAt": "string",
  "createdAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/emissions/calculate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"dispatchId\": null,
  \"legId\": null,
  \"vehicleId\": null,
  \"cargoId\": null,
  \"routeId\": null,
  \"transportDocumentId\": null,
  \"distanceKm\": null,
  \"freightWeightKg\": null,
  \"vehicleEuroClass\": null,
  \"fuelType\": null,
  \"calculationMode\": \"PLANNED\",
  \"vehicleSegment\": null,
  \"loadPct\": null,
  \"loadBucket\": null,
  \"emptyKmShare\": null,
  \"gridMixRegion\": null
}"

Freight Lanes

Showing 16 of 16 endpoints
GET/api/freight/lanes
Auth requiredlanes.view

List freight lanes

Requires features: lanes.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idsqueryNoany
originRegionIdqueryNoany
destinationRegionIdqueryNoany
railFeasibilityqueryNoany
recommendedModequeryNoany
isActivequeryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Lanes returned
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "originRegionId": "00000000-0000-4000-8000-000000000000",
      "destinationRegionId": "00000000-0000-4000-8000-000000000000",
      "originLabel": "string",
      "destinationLabel": "string",
      "originCentroid": null,
      "destinationCentroid": null,
      "roadDistanceKm": null,
      "railDistanceKm": null,
      "distanceSource": null,
      "distanceSourceVersion": null,
      "distanceUpdatedAt": null,
      "railFeasibility": "direct_siding",
      "nearestOriginTerminalId": null,
      "nearestDestTerminalId": null,
      "originLastMileKm": null,
      "destLastMileKm": null,
      "avgPriceRoadPerTon": null,
      "avgPriceRailPerTon": null,
      "avgTransitRoadHours": null,
      "avgTransitRailHours": null,
      "co2RoadPerTonKm": null,
      "co2RailPerTonKm": null,
      "volumeRoadLast90d": 1,
      "volumeRailLast90d": 1,
      "demandSupplyRatio": null,
      "recommendedMode": null,
      "recommendationConfidence": null,
      "recommendationUpdatedAt": null,
      "isActive": true,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/lanes?page=1&pageSize=50&sortField=updatedAt&sortDir=desc" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/lanes/{id}
Auth requiredlanes.view

Get freight lane detail

Requires features: lanes.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Lane returned
Content-Type: application/json
{
  "lane": {
    "id": "00000000-0000-4000-8000-000000000000",
    "tenantId": null,
    "organizationId": null,
    "originRegionId": "00000000-0000-4000-8000-000000000000",
    "destinationRegionId": "00000000-0000-4000-8000-000000000000",
    "originLabel": "string",
    "destinationLabel": "string",
    "originCentroid": null,
    "destinationCentroid": null,
    "roadDistanceKm": null,
    "railDistanceKm": null,
    "distanceSource": null,
    "distanceSourceVersion": null,
    "distanceUpdatedAt": null,
    "railFeasibility": "direct_siding",
    "nearestOriginTerminalId": null,
    "nearestDestTerminalId": null,
    "originLastMileKm": null,
    "destLastMileKm": null,
    "avgPriceRoadPerTon": null,
    "avgPriceRailPerTon": null,
    "avgTransitRoadHours": null,
    "avgTransitRailHours": null,
    "co2RoadPerTonKm": null,
    "co2RailPerTonKm": null,
    "volumeRoadLast90d": 1,
    "volumeRailLast90d": 1,
    "demandSupplyRatio": null,
    "recommendedMode": null,
    "recommendationConfidence": null,
    "recommendationUpdatedAt": null,
    "isActive": true,
    "createdAt": null,
    "updatedAt": null
  },
  "latestSnapshots": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "snapshotDate": "string",
      "mode": "road",
      "shipmentCount": 1,
      "totalTons": 1,
      "avgPricePerTon": null,
      "avgTransitHours": null,
      "rebuiltAt": null
    }
  ],
  "sourceSummary": {
    "deliveredShipmentsLast90d": 1,
    "lastDeliveredAt": null
  }
}
404Lane not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/lanes/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/freight/lanes/{id}
Auth requiredlanes.manage

Update freight lane metadata

Requires features: lanes.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "roadDistanceKm": null,
  "railDistanceKm": null,
  "distanceSource": null,
  "distanceSourceVersion": null,
  "nearestOriginTerminalId": null,
  "nearestDestTerminalId": null,
  "originLastMileKm": null,
  "destLastMileKm": null,
  "recommendedMode": null,
  "recommendationConfidence": null
}

Responses

200Lane updated
Content-Type: application/json
{
  "ok": true
}
404Lane not found
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/freight/lanes/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"roadDistanceKm\": null,
  \"railDistanceKm\": null,
  \"distanceSource\": null,
  \"distanceSourceVersion\": null,
  \"nearestOriginTerminalId\": null,
  \"nearestDestTerminalId\": null,
  \"originLastMileKm\": null,
  \"destLastMileKm\": null,
  \"recommendedMode\": null,
  \"recommendationConfidence\": null
}"
GET/api/freight/lanes/{id}/capacity-supply
Auth requiredlanes.viewmarketplace.capacity_offers.view

List active capacity offer supply for a freight lane

Requires features: lanes.view, marketplace.capacity_offers.view

Parameters

NameInRequiredSchemaDescription
idpathYesany
modequeryNoany
dateFromqueryYesany
dateToqueryYesany

Responses

200Lane capacity supply returned
Content-Type: application/json
{
  "items": [
    {
      "laneId": "00000000-0000-4000-8000-000000000000",
      "date": "string",
      "mode": "road",
      "capacityOffersCount": 1
    }
  ]
}
404Lane not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/lanes/:id/capacity-supply?dateFrom=string&dateTo=string" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/lanes/{id}/history
Auth requiredlanes.view

List freight lane snapshots

Requires features: lanes.view

Parameters

NameInRequiredSchemaDescription
idpathYesany
modequeryNoany
dateFromqueryNoany
dateToqueryNoany
pagequeryNoany
pageSizequeryNoany

Responses

200Lane snapshots returned
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "laneId": "00000000-0000-4000-8000-000000000000",
      "snapshotDate": "string",
      "mode": "road",
      "shipmentCount": 1,
      "totalTons": 1,
      "avgPricePerTon": null,
      "minPricePerTon": null,
      "maxPricePerTon": null,
      "avgTransitHours": null,
      "onTimeDeliveryPct": null,
      "capacityOffersCount": 1,
      "demandSupplyRatio": null,
      "sourceShipmentIds": [
        "00000000-0000-4000-8000-000000000000"
      ],
      "calculationVersion": "string",
      "createdAt": null,
      "updatedAt": null,
      "rebuiltAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/lanes/:id/history?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/lanes/participant-stats
Auth requiredlanes.view

List completed-shipment participant stats for freight lanes

Requires features: lanes.view

Parameters

NameInRequiredSchemaDescription
laneIdqueryNoany
laneFingerprintqueryNoany
participantProfileIdqueryNoany
carrierOrganizationIdqueryNoany
modequeryNoany
cargoSegmentqueryNoany
minCompletedShipmentCountqueryNoany
pagequeryNoany
pageSizequeryNoany

Responses

200Participant stats returned
Content-Type: application/json
{
  "items": [
    {
      "id": null,
      "laneId": null,
      "laneFingerprint": "string",
      "participantProfileId": "00000000-0000-4000-8000-000000000000",
      "carrierOrganizationId": null,
      "mode": "road",
      "cargoSegment": null,
      "completedShipmentCount": 1,
      "completedShipmentCount90d": 1,
      "totalTons": 1,
      "totalTons90d": 1,
      "onTimeDeliveryPct": null,
      "avgTransitHours": null,
      "firstCompletedAt": null,
      "lastCompletedAt": null,
      "rebuiltAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/lanes/participant-stats?mode=any&page=1&pageSize=20" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/lanes/participant-stats/rebuild
Auth requiredlanes.rebuild_participant_stats

Start a participant stat rebuild from completed shipment facts

Requires features: lanes.rebuild_participant_stats

Request body (application/json)

{}

Responses

202Participant stat rebuild started
Content-Type: application/json
{
  "ok": true,
  "progressJobId": null
}
400Invalid rebuild payload
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/lanes/participant-stats/rebuild" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
GET/api/freight/lanes/regions
Auth requiredlanes.view

List regions

Returns a paginated collection of regions scoped to the authenticated organization. Requires features: lanes.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
regionTypequeryNoany
countryCodequeryNoany
isActivequeryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Paginated regions
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "code": "string",
      "name": "string",
      "regionType": null,
      "countryCode": "string",
      "centroid": null,
      "centroidLat": null,
      "centroidLng": null,
      "radiusKm": null,
      "parentRegionId": null,
      "resolutionPriority": 1,
      "source": null,
      "sourceRevision": null,
      "geometryQuality": null,
      "isActive": true,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/lanes/regions?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/lanes/regions
Auth requiredlanes.manage

Create region

Creates a freight lane region. Requires features: lanes.manage

Request body (application/json)

{
  "code": "string",
  "name": "string",
  "regionType": "city",
  "countryCode": "string",
  "boundary": null,
  "centroid": null,
  "radiusKm": null,
  "parentRegionId": null,
  "source": null,
  "sourceRevision": null,
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Region created
Content-Type: application/json
{
  "id": null
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/lanes/regions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"code\": \"string\",
  \"name\": \"string\",
  \"regionType\": \"city\",
  \"countryCode\": \"string\",
  \"boundary\": null,
  \"centroid\": null,
  \"radiusKm\": null,
  \"parentRegionId\": null,
  \"source\": null,
  \"sourceRevision\": null,
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/freight/lanes/regions
Auth requiredlanes.manage

Update region

Updates a freight lane region. Requires features: lanes.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "boundary": null,
  "centroid": null,
  "radiusKm": null,
  "parentRegionId": null,
  "source": null,
  "sourceRevision": null
}

Responses

200Region updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/freight/lanes/regions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"boundary\": null,
  \"centroid\": null,
  \"radiusKm\": null,
  \"parentRegionId\": null,
  \"source\": null,
  \"sourceRevision\": null
}"
DELETE/api/freight/lanes/regions
Auth requiredlanes.manage

Delete region

Soft deletes a freight lane region. Requires features: lanes.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Region deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/freight/lanes/regions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/freight/lanes/regions/{id}
Auth requiredlanes.view

Get freight lane region detail

Requires features: lanes.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Region returned
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": null,
  "organizationId": null,
  "code": "string",
  "name": "string",
  "regionType": null,
  "countryCode": "string",
  "centroid": null,
  "centroidLat": null,
  "centroidLng": null,
  "radiusKm": null,
  "parentRegionId": null,
  "resolutionPriority": 1,
  "source": null,
  "sourceRevision": null,
  "geometryQuality": null,
  "isActive": true,
  "createdAt": null,
  "updatedAt": null,
  "boundary": null
}
404Region not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/lanes/regions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/lanes/regions/overlap
Auth requiredlanes.view

Find freight lane regions overlapping a boundary

Requires features: lanes.view

Request body (application/json)

{
  "limit": 50
}

Responses

200Overlapping regions returned
Content-Type: application/json
{
  "matches": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "code": "string",
      "name": "string",
      "regionType": null,
      "countryCode": "string",
      "centroid": null,
      "centroidLat": null,
      "centroidLng": null,
      "radiusKm": null,
      "parentRegionId": null,
      "resolutionPriority": 1,
      "source": null,
      "sourceRevision": null,
      "geometryQuality": null,
      "isActive": true,
      "createdAt": null,
      "updatedAt": null
    }
  ]
}
422Invalid overlap body
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/lanes/regions/overlap" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"limit\": 50
}"
GET/api/freight/lanes/regions/resolve
Auth requiredlanes.view

Resolve freight lane regions for a point or location

Requires features: lanes.view

Parameters

NameInRequiredSchemaDescription
locationIdqueryNoany
latqueryNoany
lngqueryNoany
regionTypequeryNoany
countryCodequeryNoany
includeInactivequeryNoany
limitqueryNoany

Responses

200Region matches returned
Content-Type: application/json
{
  "input": {
    "lat": 1,
    "lng": 1
  },
  "matches": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "code": "string",
      "name": "string",
      "regionType": null,
      "countryCode": "string",
      "geometryQuality": null,
      "matchType": "contains",
      "resolutionPriority": 1
    }
  ]
}
400Invalid region resolve query
Content-Type: application/json
"string"
404Location not found
Content-Type: application/json
"string"
422Location has no usable coordinates
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/lanes/regions/resolve?limit=10" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/lanes/resolve
Auth requiredlanes.manage

Resolve or create freight lane

Requires features: lanes.manage

Request body (application/json)

{
  "source": "manual"
}

Responses

200Lane resolved
Content-Type: application/json
{
  "laneId": "00000000-0000-4000-8000-000000000000",
  "created": true,
  "originRegionId": "00000000-0000-4000-8000-000000000000",
  "destinationRegionId": "00000000-0000-4000-8000-000000000000"
}
422Lane cannot be resolved
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/lanes/resolve" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"source\": \"manual\"
}"
POST/api/freight/lanes/snapshots/rebuild
Auth requiredlanes.rebuild_snapshots

Start freight lane snapshot rebuild

Requires features: lanes.rebuild_snapshots

Request body (application/json)

{
  "dateFrom": "string",
  "dateTo": "string"
}

Responses

202Rebuild started
Content-Type: application/json
{
  "ok": true,
  "progressJobId": "00000000-0000-4000-8000-000000000000",
  "message": "string"
}
400Invalid payload
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/lanes/snapshots/rebuild" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"dateFrom\": \"string\",
  \"dateTo\": \"string\"
}"

Freight Locations

Showing 6 of 6 endpoints
GET/api/freight/locations
Auth requiredlocations.view

List locations

Returns a paginated collection of locations scoped to the authenticated organization. Requires features: locations.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
typequeryNoany
supportedModequeryNoany
capabilityqueryNoany
isActivequeryNoany
slotBookingEnabledqueryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Paginated locations
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "name": "string",
      "code": null,
      "type": null,
      "unlocode": null,
      "address": {
        "street": "string",
        "city": "string",
        "postalCode": "string",
        "country": "string",
        "region": null
      },
      "supportedModes": [
        "ROAD"
      ],
      "capabilities": [
        "CONTAINER"
      ],
      "geofenceRadiusM": null,
      "slotBookingEnabled": true,
      "operatingHours": null,
      "avgHandlingTimeMin": null,
      "contactName": null,
      "contactPhone": null,
      "gateInstructions": null,
      "isActive": true,
      "latitude": null,
      "longitude": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/locations?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/locations
Auth requiredlocations.manage

Create location

Creates a freight location. Requires features: locations.manage

Request body (application/json)

{
  "name": "string",
  "code": null,
  "type": "PORT",
  "unlocode": null,
  "address": {
    "street": "string",
    "city": "string",
    "postalCode": "string",
    "country": "string",
    "region": null
  },
  "supportedModes": [
    "ROAD"
  ],
  "capabilities": [],
  "latitude": 1,
  "longitude": 1,
  "geofenceRadiusM": null,
  "operatingHours": null,
  "avgHandlingTimeMin": null,
  "contactName": null,
  "contactPhone": null,
  "gateInstructions": null,
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Location created
Content-Type: application/json
{
  "id": null,
  "locationId": null
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/locations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"code\": null,
  \"type\": \"PORT\",
  \"unlocode\": null,
  \"address\": {
    \"street\": \"string\",
    \"city\": \"string\",
    \"postalCode\": \"string\",
    \"country\": \"string\",
    \"region\": null
  },
  \"supportedModes\": [
    \"ROAD\"
  ],
  \"capabilities\": [],
  \"latitude\": 1,
  \"longitude\": 1,
  \"geofenceRadiusM\": null,
  \"operatingHours\": null,
  \"avgHandlingTimeMin\": null,
  \"contactName\": null,
  \"contactPhone\": null,
  \"gateInstructions\": null,
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\",
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/freight/locations
Auth requiredlocations.manage

Update location

Updates a freight location. Requires features: locations.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "code": null,
  "unlocode": null,
  "geofenceRadiusM": null,
  "operatingHours": null,
  "avgHandlingTimeMin": null,
  "contactName": null,
  "contactPhone": null,
  "gateInstructions": null
}

Responses

200Location updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/freight/locations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"code\": null,
  \"unlocode\": null,
  \"geofenceRadiusM\": null,
  \"operatingHours\": null,
  \"avgHandlingTimeMin\": null,
  \"contactName\": null,
  \"contactPhone\": null,
  \"gateInstructions\": null
}"
DELETE/api/freight/locations
Auth requiredlocations.manage

Delete location

Soft deletes a freight location. Requires features: locations.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Location deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/freight/locations" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/freight/locations/{id}
Auth requiredlocations.view

Get freight location detail

Requires features: locations.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Location returned
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": null,
  "organizationId": null,
  "name": "string",
  "code": null,
  "type": null,
  "unlocode": null,
  "address": {
    "street": "string",
    "city": "string",
    "postalCode": "string",
    "country": "string",
    "region": null
  },
  "supportedModes": [
    "ROAD"
  ],
  "capabilities": [
    "CONTAINER"
  ],
  "geofenceRadiusM": null,
  "slotBookingEnabled": true,
  "operatingHours": null,
  "avgHandlingTimeMin": null,
  "contactName": null,
  "contactPhone": null,
  "gateInstructions": null,
  "isActive": true,
  "latitude": null,
  "longitude": null,
  "createdAt": null,
  "updatedAt": null
}
404Location not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/locations/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/locations/nearby
Auth requiredlocations.view

Find freight locations by proximity

Requires features: locations.view

Parameters

NameInRequiredSchemaDescription
latqueryYesany
lngqueryYesany
radiusKmqueryNoany
limitqueryNoany
typequeryNoany
supportedModequeryNoany
capabilityqueryNoany

Responses

200Nearby locations returned
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": null,
      "organizationId": null,
      "name": "string",
      "code": null,
      "type": null,
      "unlocode": null,
      "address": {
        "street": "string",
        "city": "string",
        "postalCode": "string",
        "country": "string",
        "region": null
      },
      "supportedModes": [
        "ROAD"
      ],
      "capabilities": [
        "CONTAINER"
      ],
      "geofenceRadiusM": null,
      "slotBookingEnabled": true,
      "operatingHours": null,
      "avgHandlingTimeMin": null,
      "contactName": null,
      "contactPhone": null,
      "gateInstructions": null,
      "isActive": true,
      "latitude": null,
      "longitude": null,
      "createdAt": null,
      "updatedAt": null,
      "distanceMeters": null
    }
  ],
  "radiusKm": 1,
  "count": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/locations/nearby?lat=1&lng=1&radiusKm=50&limit=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Freight Marketplace

Showing 20 of 34 endpoints
GET/api/freight/marketplace/capacity-offers
Auth requiredmarketplace.capacity_offers.view

List capacity offers

Requires features: marketplace.capacity_offers.view

Responses

200Paginated capacity offer list
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "offerNumber": "string",
      "status": "string",
      "carrierParticipantId": "string",
      "participantCapabilityId": null,
      "laneId": null,
      "originRegionId": null,
      "destinationRegionId": null,
      "mode": "string",
      "cargoSegment": "string",
      "equipmentType": "string",
      "equipmentSubtype": null,
      "totalCapacityUnits": 1,
      "availableCapacityUnits": 1,
      "heldCapacityUnits": 1,
      "confirmedCapacityUnits": 1,
      "availableFrom": "string",
      "availableTo": "string",
      "validFrom": null,
      "validTo": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/marketplace/capacity-offers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/marketplace/capacity-offers
Auth requiredmarketplace.capacity_offers.create

Create capacity offer

Requires features: marketplace.capacity_offers.create

Request body (application/json)

"string"

Responses

201Capacity offer created
Content-Type: application/json
{
  "id": "string",
  "offerNumber": "string",
  "status": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/capacity-offers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/marketplace/capacity-offers/{id}
Auth requiredmarketplace.capacity_offers.view

Get capacity offer

Requires features: marketplace.capacity_offers.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Capacity offer detail
Content-Type: application/json
{
  "id": "string",
  "offerNumber": "string",
  "status": "string",
  "carrierParticipantId": "string",
  "participantCapabilityId": null,
  "laneId": null,
  "originRegionId": null,
  "destinationRegionId": null,
  "mode": "string",
  "cargoSegment": "string",
  "equipmentType": "string",
  "equipmentSubtype": null,
  "totalCapacityUnits": 1,
  "availableCapacityUnits": 1,
  "heldCapacityUnits": 1,
  "confirmedCapacityUnits": 1,
  "availableFrom": "string",
  "availableTo": "string",
  "validFrom": null,
  "validTo": null,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/marketplace/capacity-offers/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/freight/marketplace/capacity-offers/{id}
Auth requiredmarketplace.capacity_offers.manage

Update capacity offer

Requires features: marketplace.capacity_offers.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "id": "string",
  "participantCapabilityId": null,
  "laneId": null,
  "originRegionId": null,
  "destinationRegionId": null,
  "equipmentSubtype": null,
  "heldCapacityUnits": 0,
  "confirmedCapacityUnits": 0,
  "maxPayloadTons": null,
  "maxWeightPerUnitTons": null,
  "requiresAdr": false,
  "requiresReefer": false,
  "requiresOversized": false,
  "tempMinC": null,
  "tempMaxC": null,
  "validFrom": null,
  "validTo": null,
  "priceHintAmount": null,
  "priceHintCurrency": null,
  "priceHintUnit": null,
  "termsText": null,
  "carrierNotes": null,
  "internalNotes": null,
  "metadataJson": null
}

Responses

200Capacity offer updated
Content-Type: application/json
{
  "id": "string",
  "offerNumber": "string",
  "status": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/freight/marketplace/capacity-offers/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\",
  \"participantCapabilityId\": null,
  \"laneId\": null,
  \"originRegionId\": null,
  \"destinationRegionId\": null,
  \"equipmentSubtype\": null,
  \"heldCapacityUnits\": 0,
  \"confirmedCapacityUnits\": 0,
  \"maxPayloadTons\": null,
  \"maxWeightPerUnitTons\": null,
  \"requiresAdr\": false,
  \"requiresReefer\": false,
  \"requiresOversized\": false,
  \"tempMinC\": null,
  \"tempMaxC\": null,
  \"validFrom\": null,
  \"validTo\": null,
  \"priceHintAmount\": null,
  \"priceHintCurrency\": null,
  \"priceHintUnit\": null,
  \"termsText\": null,
  \"carrierNotes\": null,
  \"internalNotes\": null,
  \"metadataJson\": null
}"
POST/api/freight/marketplace/capacity-offers/{id}/deactivate
Auth requiredmarketplace.capacity_offers.manage

Deactivate capacity offer

Requires features: marketplace.capacity_offers.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "reasonText": null
}

Responses

200Capacity offer deactivated
Content-Type: application/json
{
  "id": "string",
  "status": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/capacity-offers/:id/deactivate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"reasonText\": null
}"
POST/api/freight/marketplace/capacity-offers/{id}/expire
Auth requiredmarketplace.capacity_offers.manage

Expire capacity offer

Requires features: marketplace.capacity_offers.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "now": null
}

Responses

200Capacity offer expired
Content-Type: application/json
{
  "id": "string",
  "status": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/capacity-offers/:id/expire" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"now\": null
}"
POST/api/freight/marketplace/capacity-offers/{id}/publish
Auth requiredmarketplace.capacity_offers.manage

Publish capacity offer

Requires features: marketplace.capacity_offers.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Capacity offer published
Content-Type: application/json
{
  "id": "string",
  "status": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/capacity-offers/:id/publish" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/marketplace/capacity-offers/{id}/withdraw
Auth requiredmarketplace.capacity_offers.manage

Withdraw capacity offer

Requires features: marketplace.capacity_offers.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "reasonText": null
}

Responses

200Capacity offer withdrawn
Content-Type: application/json
{
  "id": "string",
  "status": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/capacity-offers/:id/withdraw" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"reasonText\": null
}"
POST/api/freight/marketplace/capacity-offers/expire-due
Auth requiredmarketplace.capacity_offers.manage

Start capacity offer expiry job

Requires features: marketplace.capacity_offers.manage

Request body (application/json)

{
  "limit": 100
}

Responses

202Expiry job started
Content-Type: application/json
{
  "ok": true,
  "progressJobId": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/capacity-offers/expire-due" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"limit\": 100
}"
GET/api/freight/marketplace/discovery/shipments
Auth requiredmarketplace.discovery.view

List discoverable marketplace shipments

Requires features: marketplace.discovery.view

Responses

200Cursor page of sanitized marketplace discovery shipments
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "discoveryReference": "string",
      "status": "published",
      "visibility": "tenant",
      "marketType": "string",
      "cargoSegment": "string",
      "modeConstraint": "string",
      "weightTons": "string",
      "volumeM3": null,
      "unitCount": null,
      "isDangerous": true,
      "requiresTempControl": true,
      "pickupEarliest": "string",
      "pickupLatest": "string",
      "deliveryDeadline": null,
      "laneId": null,
      "originSummary": null,
      "destinationSummary": null,
      "currency": "string",
      "pricingAvailable": true,
      "canSubmitProposal": true,
      "visibilityReason": "string",
      "eligibilityReasons": [
        "string"
      ]
    }
  ],
  "nextCursor": null,
  "pageSize": 1
}
400Invalid discovery query
Content-Type: application/json
{
  "error": "string",
  "code": "INVALID_DISCOVERY_QUERY"
}
404Shipment not found
Content-Type: application/json
{
  "error": "string",
  "code": "INVALID_DISCOVERY_QUERY"
}
500Discovery failure
Content-Type: application/json
{
  "error": "string",
  "code": "INVALID_DISCOVERY_QUERY"
}
503Participant eligibility unavailable
Content-Type: application/json
{
  "error": "string",
  "code": "INVALID_DISCOVERY_QUERY"
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/marketplace/discovery/shipments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/marketplace/discovery/shipments/{id}
Auth requiredmarketplace.discovery.view

Load a discoverable marketplace shipment

Requires features: marketplace.discovery.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Sanitized marketplace discovery shipment detail
Content-Type: application/json
{
  "item": {
    "id": "string",
    "discoveryReference": "string",
    "status": "published",
    "visibility": "tenant",
    "marketType": "string",
    "cargoSegment": "string",
    "modeConstraint": "string",
    "weightTons": "string",
    "volumeM3": null,
    "unitCount": null,
    "isDangerous": true,
    "requiresTempControl": true,
    "pickupEarliest": "string",
    "pickupLatest": "string",
    "deliveryDeadline": null,
    "laneId": null,
    "originSummary": null,
    "destinationSummary": null,
    "currency": "string",
    "pricingAvailable": true,
    "canSubmitProposal": true,
    "visibilityReason": "string",
    "eligibilityReasons": [
      "string"
    ]
  },
  "proposalSubmit": {
    "canSubmit": true,
    "participantId": null,
    "reasons": [
      "string"
    ]
  }
}
404Shipment not found
Content-Type: application/json
{
  "error": "string",
  "code": "INVALID_DISCOVERY_QUERY"
}
500Discovery failure
Content-Type: application/json
{
  "error": "string",
  "code": "INVALID_DISCOVERY_QUERY"
}
503Participant eligibility unavailable
Content-Type: application/json
{
  "error": "string",
  "code": "INVALID_DISCOVERY_QUERY"
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/marketplace/discovery/shipments/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/marketplace/proposals
Auth requiredmarketplace.proposals.view

List proposals visible to the actor

Requires features: marketplace.proposals.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
statusqueryNoany
shipmentIdqueryNoany
carrierParticipantIdqueryNoany
carrierOrganizationIdqueryNoany
rolequeryNoany

Responses

200Paginated proposal list
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "proposalNumber": "string",
      "shipmentId": "string",
      "status": "string",
      "direction": "string",
      "carrierParticipantId": "string",
      "carrierOrganizationId": "string",
      "capacityOfferId": null,
      "capacityReservationId": null,
      "capacityReservationStatus": null,
      "totalAmount": "string",
      "currency": "string",
      "expiresAt": null,
      "submittedAt": null,
      "acceptedAt": null,
      "createdAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/marketplace/proposals?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/marketplace/proposals/{id}
Auth requiredmarketplace.proposals.view

Get visible proposal detail

Requires features: marketplace.proposals.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Proposal detail
Content-Type: application/json
{
  "id": "string",
  "proposalNumber": "string",
  "shipmentId": "string",
  "status": "string",
  "carrierOrganizationId": "string",
  "carrierParticipantId": "string",
  "capacityOfferId": null,
  "capacityReservationId": null,
  "capacityReservationStatus": null,
  "totalAmount": "string",
  "currency": "string",
  "costLines": [
    {
      "id": "string",
      "amount": "string",
      "currency": "string"
    }
  ]
}
404Proposal not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/marketplace/proposals/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/marketplace/proposals/{id}/accept
Auth requiredmarketplace.proposals.manage

Accept proposal and book shipment

Requires features: marketplace.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "id": "string"
}

Responses

200Proposal accepted
Content-Type: application/json
{
  "id": "string",
  "proposalId": "string",
  "shipmentId": "string",
  "shipmentStatus": "booked",
  "rejectedCompetingProposalIds": [
    "string"
  ],
  "affectedLegIds": [
    "string"
  ],
  "capacityOfferId": null,
  "capacityReservationId": null,
  "capacityReservationStatus": null
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/proposals/:id/accept" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\"
}"
POST/api/freight/marketplace/proposals/{id}/counter
Auth requiredmarketplace.proposals.submit

Create a counter proposal revision

Requires features: marketplace.proposals.submit

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "validFrom": null,
  "expiresAt": null,
  "termsText": null,
  "carrierNotes": null,
  "shipperNotes": null,
  "metadataJson": null,
  "costLines": [
    {
      "kind": "base_freight",
      "effect": "charge",
      "description": null,
      "shipmentLegId": null,
      "quantity": 1,
      "unitCode": "shipment",
      "unitPrice": 1,
      "taxRate": null,
      "taxAmount": null
    }
  ],
  "pricingEstimateId": null,
  "capacityOfferId": null
}

Responses

201Proposal countered
Content-Type: application/json
{
  "id": "string",
  "status": "string",
  "totalAmount": "string",
  "currency": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/proposals/:id/counter" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"validFrom\": null,
  \"expiresAt\": null,
  \"termsText\": null,
  \"carrierNotes\": null,
  \"shipperNotes\": null,
  \"metadataJson\": null,
  \"costLines\": [
    {
      \"kind\": \"base_freight\",
      \"effect\": \"charge\",
      \"description\": null,
      \"shipmentLegId\": null,
      \"quantity\": 1,
      \"unitCode\": \"shipment\",
      \"unitPrice\": 1,
      \"taxRate\": null,
      \"taxAmount\": null
    }
  ],
  \"pricingEstimateId\": null,
  \"capacityOfferId\": null
}"
POST/api/freight/marketplace/proposals/{id}/reject
Auth requiredmarketplace.proposals.manage

Reject an open proposal

Requires features: marketplace.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "id": "string",
  "reasonCode": "other",
  "reasonText": null
}

Responses

200Proposal rejected
Content-Type: application/json
{
  "id": "string",
  "status": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/proposals/:id/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\",
  \"reasonCode\": \"other\",
  \"reasonText\": null
}"
POST/api/freight/marketplace/proposals/{id}/withdraw
Auth requiredmarketplace.proposals.submit

Withdraw an open carrier-owned proposal

Requires features: marketplace.proposals.submit

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "id": "string",
  "reasonText": null
}

Responses

200Proposal withdrawn
Content-Type: application/json
{
  "id": "string",
  "status": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/proposals/:id/withdraw" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\",
  \"reasonText\": null
}"
POST/api/freight/marketplace/proposals/expire-due
Auth requiredmarketplace.proposals.manage

Start proposal expiry job

Requires features: marketplace.proposals.manage

Request body (application/json)

{
  "limit": 100
}

Responses

202Expiry job started
Content-Type: application/json
{
  "ok": true,
  "progressJobId": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/proposals/expire-due" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"limit\": 100
}"
GET/api/freight/marketplace/shipments
Auth requiredmarketplace.view

List shipments

Requires features: marketplace.view

Responses

200Paginated shipment list
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "shipmentNumber": "string",
      "status": "string",
      "cargoSegment": "string",
      "marketType": "string",
      "originLocationId": "string",
      "destinationLocationId": "string",
      "weightTons": "string",
      "pickupEarliest": "string",
      "createdAt": "string",
      "legacyOrderId": null,
      "legacySalesShipmentId": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/marketplace/shipments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/marketplace/shipments
Auth requiredmarketplace.create

Create shipment

Requires features: marketplace.create

Request body (application/json)

{
  "tenantId": "string",
  "organizationId": "string",
  "shipperId": "string",
  "consigneeId": null,
  "cargoSegment": "container_iso",
  "cargoId": null,
  "weightTons": 1,
  "volumeM3": null,
  "unitCount": null,
  "commodityDescription": null,
  "commodityNhm": null,
  "isDangerous": false,
  "adrRidClass": null,
  "unNumber": null,
  "requiresTempControl": false,
  "tempMinC": null,
  "tempMaxC": null,
  "originLocationId": "string",
  "destinationLocationId": "string",
  "laneId": null,
  "pickupEarliest": "string",
  "pickupLatest": "string",
  "deliveryDeadline": null,
  "isRecurring": false,
  "recurrencePattern": null,
  "modeConstraint": "auto",
  "modePreference": null,
  "marketType": "contract",
  "contractRateId": null,
  "maxPricePerUnit": null,
  "priceUnit": null,
  "currency": "PLN",
  "visibility": "private",
  "invitedCarrierIds": null,
  "legacyOrderId": null,
  "legacySalesShipmentId": null,
  "notes": null,
  "tags": null,
  "createdByUserId": "string"
}

Responses

201Shipment created
Content-Type: application/json
{
  "id": "string",
  "shipmentNumber": "string",
  "legacySalesShipmentId": null
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/marketplace/shipments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"string\",
  \"organizationId\": \"string\",
  \"shipperId\": \"string\",
  \"consigneeId\": null,
  \"cargoSegment\": \"container_iso\",
  \"cargoId\": null,
  \"weightTons\": 1,
  \"volumeM3\": null,
  \"unitCount\": null,
  \"commodityDescription\": null,
  \"commodityNhm\": null,
  \"isDangerous\": false,
  \"adrRidClass\": null,
  \"unNumber\": null,
  \"requiresTempControl\": false,
  \"tempMinC\": null,
  \"tempMaxC\": null,
  \"originLocationId\": \"string\",
  \"destinationLocationId\": \"string\",
  \"laneId\": null,
  \"pickupEarliest\": \"string\",
  \"pickupLatest\": \"string\",
  \"deliveryDeadline\": null,
  \"isRecurring\": false,
  \"recurrencePattern\": null,
  \"modeConstraint\": \"auto\",
  \"modePreference\": null,
  \"marketType\": \"contract\",
  \"contractRateId\": null,
  \"maxPricePerUnit\": null,
  \"priceUnit\": null,
  \"currency\": \"PLN\",
  \"visibility\": \"private\",
  \"invitedCarrierIds\": null,
  \"legacyOrderId\": null,
  \"legacySalesShipmentId\": null,
  \"notes\": null,
  \"tags\": null,
  \"createdByUserId\": \"string\"
}"

Freight Carrier Matchers

Showing 8 of 8 endpoints
POST/api/freight/matchers/candidates/{id}/reject
Auth requiredmatchers.shortlist

Reject candidate

Requires features: matchers.shortlist

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null,
  "actorUserId": null
}

Responses

200Candidate rejected
Content-Type: application/json
{
  "id": "string",
  "matchRunId": "string",
  "shipmentId": "string",
  "participantProfileId": "string",
  "carrierOrganizationId": null,
  "carrierDisplayName": null,
  "decisionStatus": "candidate",
  "recommendation": "recommended",
  "score": 1,
  "confidenceScore": 1,
  "rank": 1,
  "eligibilityScore": null,
  "lanePreferenceScore": null,
  "laneHistoryScore": null,
  "pricingScore": null,
  "reputationScore": null,
  "estimatedTotalAmount": null,
  "estimatedCurrency": null,
  "pricingStatus": null,
  "accessTier": null,
  "excludedReasonCode": null,
  "decisionNote": null,
  "decidedAt": null,
  "decidedByUserId": null,
  "explanation": null,
  "sourceSnapshot": null,
  "createdAt": null,
  "updatedAt": null
}
404Candidate not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/matchers/candidates/:id/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null,
  \"actorUserId\": null
}"
POST/api/freight/matchers/candidates/{id}/shortlist
Auth requiredmatchers.shortlist

Shortlist candidate

Requires features: matchers.shortlist

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null,
  "actorUserId": null
}

Responses

200Candidate shortlisted
Content-Type: application/json
{
  "id": "string",
  "matchRunId": "string",
  "shipmentId": "string",
  "participantProfileId": "string",
  "carrierOrganizationId": null,
  "carrierDisplayName": null,
  "decisionStatus": "candidate",
  "recommendation": "recommended",
  "score": 1,
  "confidenceScore": 1,
  "rank": 1,
  "eligibilityScore": null,
  "lanePreferenceScore": null,
  "laneHistoryScore": null,
  "pricingScore": null,
  "reputationScore": null,
  "estimatedTotalAmount": null,
  "estimatedCurrency": null,
  "pricingStatus": null,
  "accessTier": null,
  "excludedReasonCode": null,
  "decisionNote": null,
  "decidedAt": null,
  "decidedByUserId": null,
  "explanation": null,
  "sourceSnapshot": null,
  "createdAt": null,
  "updatedAt": null
}
404Candidate not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/matchers/candidates/:id/shortlist" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null,
  \"actorUserId\": null
}"
GET/api/freight/matchers/runs
Auth requiredmatchers.view

List carrier match runs

Requires features: matchers.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idsqueryNoany
shipmentIdqueryNoany
statusqueryNoany

Responses

200Runs returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "shipmentId": "string",
      "shipmentNumber": null,
      "discoveryReference": null,
      "status": "running",
      "algorithmVersion": "string",
      "matcherMode": null,
      "cargoSegment": null,
      "laneId": null,
      "laneFingerprint": null,
      "candidateCount": 1,
      "shortlistedCount": 1,
      "excludedCount": 1,
      "scoreThreshold": 1,
      "summary": null,
      "failureMessage": null,
      "inputSnapshot": null,
      "requestedByUserId": null,
      "startedAt": null,
      "completedAt": null,
      "isCurrent": true,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1
}
400Invalid query
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/matchers/runs?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/matchers/runs
Auth requiredmatchers.run

Create carrier match run

Requires features: matchers.run

Request body (application/json)

{
  "shipmentId": "string",
  "requestedByUserId": null,
  "scoreThreshold": 0.55,
  "candidateLimit": 20
}

Responses

200Run created
Content-Type: application/json
{
  "id": "string",
  "shipmentId": "string",
  "shipmentNumber": null,
  "discoveryReference": null,
  "status": "running",
  "algorithmVersion": "string",
  "matcherMode": null,
  "cargoSegment": null,
  "laneId": null,
  "laneFingerprint": null,
  "candidateCount": 1,
  "shortlistedCount": 1,
  "excludedCount": 1,
  "scoreThreshold": 1,
  "summary": null,
  "failureMessage": null,
  "inputSnapshot": null,
  "requestedByUserId": null,
  "startedAt": null,
  "completedAt": null,
  "isCurrent": true,
  "createdAt": null,
  "updatedAt": null,
  "candidates": [
    {
      "id": "string",
      "matchRunId": "string",
      "shipmentId": "string",
      "participantProfileId": "string",
      "carrierOrganizationId": null,
      "carrierDisplayName": null,
      "decisionStatus": "candidate",
      "recommendation": "recommended",
      "score": 1,
      "confidenceScore": 1,
      "rank": 1,
      "eligibilityScore": null,
      "lanePreferenceScore": null,
      "laneHistoryScore": null,
      "pricingScore": null,
      "reputationScore": null,
      "estimatedTotalAmount": null,
      "estimatedCurrency": null,
      "pricingStatus": null,
      "accessTier": null,
      "excludedReasonCode": null,
      "decisionNote": null,
      "decidedAt": null,
      "decidedByUserId": null,
      "explanation": null,
      "sourceSnapshot": null,
      "createdAt": null,
      "updatedAt": null
    }
  ]
}
422Shipment is not matchable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/matchers/runs" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"shipmentId\": \"string\",
  \"requestedByUserId\": null,
  \"scoreThreshold\": 0.55,
  \"candidateLimit\": 20
}"
GET/api/freight/matchers/runs/{id}
Auth requiredmatchers.view

Get carrier match run

Requires features: matchers.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Run returned
Content-Type: application/json
{
  "id": "string",
  "shipmentId": "string",
  "shipmentNumber": null,
  "discoveryReference": null,
  "status": "running",
  "algorithmVersion": "string",
  "matcherMode": null,
  "cargoSegment": null,
  "laneId": null,
  "laneFingerprint": null,
  "candidateCount": 1,
  "shortlistedCount": 1,
  "excludedCount": 1,
  "scoreThreshold": 1,
  "summary": null,
  "failureMessage": null,
  "inputSnapshot": null,
  "requestedByUserId": null,
  "startedAt": null,
  "completedAt": null,
  "isCurrent": true,
  "createdAt": null,
  "updatedAt": null,
  "candidates": [
    {
      "id": "string",
      "matchRunId": "string",
      "shipmentId": "string",
      "participantProfileId": "string",
      "carrierOrganizationId": null,
      "carrierDisplayName": null,
      "decisionStatus": "candidate",
      "recommendation": "recommended",
      "score": 1,
      "confidenceScore": 1,
      "rank": 1,
      "eligibilityScore": null,
      "lanePreferenceScore": null,
      "laneHistoryScore": null,
      "pricingScore": null,
      "reputationScore": null,
      "estimatedTotalAmount": null,
      "estimatedCurrency": null,
      "pricingStatus": null,
      "accessTier": null,
      "excludedReasonCode": null,
      "decisionNote": null,
      "decidedAt": null,
      "decidedByUserId": null,
      "explanation": null,
      "sourceSnapshot": null,
      "createdAt": null,
      "updatedAt": null
    }
  ]
}
404Run not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/matchers/runs/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/matchers/runs/{id}/refresh
Auth requiredmatchers.run

Refresh carrier match run

Requires features: matchers.run

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "requestedByUserId": null
}

Responses

200Run refreshed
Content-Type: application/json
{
  "id": "string",
  "shipmentId": "string",
  "shipmentNumber": null,
  "discoveryReference": null,
  "status": "running",
  "algorithmVersion": "string",
  "matcherMode": null,
  "cargoSegment": null,
  "laneId": null,
  "laneFingerprint": null,
  "candidateCount": 1,
  "shortlistedCount": 1,
  "excludedCount": 1,
  "scoreThreshold": 1,
  "summary": null,
  "failureMessage": null,
  "inputSnapshot": null,
  "requestedByUserId": null,
  "startedAt": null,
  "completedAt": null,
  "isCurrent": true,
  "createdAt": null,
  "updatedAt": null,
  "candidates": [
    {
      "id": "string",
      "matchRunId": "string",
      "shipmentId": "string",
      "participantProfileId": "string",
      "carrierOrganizationId": null,
      "carrierDisplayName": null,
      "decisionStatus": "candidate",
      "recommendation": "recommended",
      "score": 1,
      "confidenceScore": 1,
      "rank": 1,
      "eligibilityScore": null,
      "lanePreferenceScore": null,
      "laneHistoryScore": null,
      "pricingScore": null,
      "reputationScore": null,
      "estimatedTotalAmount": null,
      "estimatedCurrency": null,
      "pricingStatus": null,
      "accessTier": null,
      "excludedReasonCode": null,
      "decisionNote": null,
      "decidedAt": null,
      "decidedByUserId": null,
      "explanation": null,
      "sourceSnapshot": null,
      "createdAt": null,
      "updatedAt": null
    }
  ]
}
404Run not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/matchers/runs/:id/refresh" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"requestedByUserId\": null
}"
POST/api/freight/matchers/runs/{id}/shortlist
Auth requiredmatchers.shortlist

Shortlist run candidates

Requires features: matchers.shortlist

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null,
  "actorUserId": null
}

Responses

200Candidates shortlisted
Content-Type: application/json
{
  "id": "string",
  "shipmentId": "string",
  "shipmentNumber": null,
  "discoveryReference": null,
  "status": "running",
  "algorithmVersion": "string",
  "matcherMode": null,
  "cargoSegment": null,
  "laneId": null,
  "laneFingerprint": null,
  "candidateCount": 1,
  "shortlistedCount": 1,
  "excludedCount": 1,
  "scoreThreshold": 1,
  "summary": null,
  "failureMessage": null,
  "inputSnapshot": null,
  "requestedByUserId": null,
  "startedAt": null,
  "completedAt": null,
  "isCurrent": true,
  "createdAt": null,
  "updatedAt": null,
  "candidates": [
    {
      "id": "string",
      "matchRunId": "string",
      "shipmentId": "string",
      "participantProfileId": "string",
      "carrierOrganizationId": null,
      "carrierDisplayName": null,
      "decisionStatus": "candidate",
      "recommendation": "recommended",
      "score": 1,
      "confidenceScore": 1,
      "rank": 1,
      "eligibilityScore": null,
      "lanePreferenceScore": null,
      "laneHistoryScore": null,
      "pricingScore": null,
      "reputationScore": null,
      "estimatedTotalAmount": null,
      "estimatedCurrency": null,
      "pricingStatus": null,
      "accessTier": null,
      "excludedReasonCode": null,
      "decisionNote": null,
      "decidedAt": null,
      "decidedByUserId": null,
      "explanation": null,
      "sourceSnapshot": null,
      "createdAt": null,
      "updatedAt": null
    }
  ]
}
404Run or candidates not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/matchers/runs/:id/shortlist" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null,
  \"actorUserId\": null
}"
GET/api/freight/matchers/shipments/{id}/summary
Auth requiredmatchers.view

Get current match run for a shipment

Requires features: matchers.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Shipment matcher summary returned
Content-Type: application/json
"string"
404Shipment or run not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/matchers/shipments/:id/summary" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Freight Optimizations

Showing 8 of 8 endpoints
POST/api/freight/optimizations/candidates/{id}/accept
Auth requiredoptimizations.decide

Accept optimization candidate

Requires features: optimizations.decide

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Candidate accepted
Content-Type: application/json
{
  "id": "string",
  "runId": "string",
  "decisionStatus": "candidate",
  "dispatchDraft": null
}
404Candidate not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/optimizations/candidates/:id/accept" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
POST/api/freight/optimizations/candidates/{id}/reject
Auth requiredoptimizations.decide

Reject optimization candidate

Requires features: optimizations.decide

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Candidate rejected
Content-Type: application/json
{
  "id": "string",
  "runId": "string",
  "decisionStatus": "candidate",
  "dispatchDraft": null
}
404Candidate not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/optimizations/candidates/:id/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
GET/api/freight/optimizations/provider-health
Auth requiredoptimizations.view

Get optimization provider health

Requires features: optimizations.view

Responses

200Provider health returned
Content-Type: application/json
{
  "providers": [
    {
      "providerId": "INTERNAL_FAST",
      "label": "string",
      "ok": true,
      "source": "live",
      "checkedAt": "string",
      "degradedReasonCode": null
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/optimizations/provider-health" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/optimizations/runs
Auth requiredoptimizations.view

List optimization runs

Requires features: optimizations.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idsqueryNoany
sourceTypequeryNoany
sourceIdqueryNoany
statusqueryNoany
providerIdqueryNoany
isCurrentqueryNoany

Responses

200Optimization runs returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "sourceType": "marketplace_shipment",
      "sourceId": "string",
      "sourceLabel": null,
      "status": "running",
      "providerId": "INTERNAL_FAST",
      "objective": "balanced",
      "candidateCount": 1,
      "acceptedCandidateId": null,
      "isCurrent": true,
      "confidenceScore": null,
      "sourceMode": null,
      "degradedReasonCode": null,
      "sensitiveEvidenceAvailable": true,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}
400Invalid query
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/optimizations/runs?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/optimizations/runs
Auth requiredoptimizations.run

Create optimization run

Requires features: optimizations.run

Request body (application/json)

{
  "sourceType": "marketplace_shipment",
  "sourceId": "string",
  "objective": "balanced",
  "providerId": "INTERNAL_FAST",
  "candidateLimit": 20,
  "allowFallback": true,
  "forceRefresh": false
}

Responses

201Optimization run created
Content-Type: application/json
{
  "id": "string",
  "sourceType": "marketplace_shipment",
  "sourceId": "string",
  "sourceLabel": null,
  "status": "running",
  "providerId": "INTERNAL_FAST",
  "objective": "balanced",
  "candidateCount": 1,
  "acceptedCandidateId": null,
  "isCurrent": true,
  "confidenceScore": null,
  "sourceMode": null,
  "degradedReasonCode": null,
  "sensitiveEvidenceAvailable": true,
  "createdAt": "string",
  "updatedAt": "string",
  "summary": null,
  "candidates": [
    {
      "id": "string",
      "runId": "string",
      "assignmentType": "dispatch_assignment",
      "rank": 1,
      "score": 1,
      "confidenceScore": 1,
      "recommendation": "recommended",
      "decisionStatus": "candidate",
      "shipmentId": null,
      "matchRunId": null,
      "matchCandidateId": null,
      "participantProfileId": null,
      "carrierOrganizationId": null,
      "routingMatrixRunId": null,
      "plannedPickupAt": null,
      "plannedDeliveryAt": null,
      "displayLabel": null,
      "hardBlockers": [
        {
          "code": "string",
          "labelKey": "string",
          "kind": "hard"
        }
      ],
      "scoreComponents": [
        {
          "code": "string",
          "labelKey": "string",
          "score": 1,
          "weight": 1,
          "severity": "positive"
        }
      ],
      "dispatchDraft": null,
      "decidedAt": null,
      "decidedByUserId": null
    }
  ]
}
400Invalid request or unsupported provider
Content-Type: application/json
"string"
422Source not ready
Content-Type: application/json
"string"
503Provider unavailable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/optimizations/runs" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"sourceType\": \"marketplace_shipment\",
  \"sourceId\": \"string\",
  \"objective\": \"balanced\",
  \"providerId\": \"INTERNAL_FAST\",
  \"candidateLimit\": 20,
  \"allowFallback\": true,
  \"forceRefresh\": false
}"
GET/api/freight/optimizations/runs/{id}
Auth requiredoptimizations.view

Get optimization run

Requires features: optimizations.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Optimization run returned
Content-Type: application/json
{
  "id": "string",
  "sourceType": "marketplace_shipment",
  "sourceId": "string",
  "sourceLabel": null,
  "status": "running",
  "providerId": "INTERNAL_FAST",
  "objective": "balanced",
  "candidateCount": 1,
  "acceptedCandidateId": null,
  "isCurrent": true,
  "confidenceScore": null,
  "sourceMode": null,
  "degradedReasonCode": null,
  "sensitiveEvidenceAvailable": true,
  "createdAt": "string",
  "updatedAt": "string",
  "summary": null,
  "candidates": [
    {
      "id": "string",
      "runId": "string",
      "assignmentType": "dispatch_assignment",
      "rank": 1,
      "score": 1,
      "confidenceScore": 1,
      "recommendation": "recommended",
      "decisionStatus": "candidate",
      "shipmentId": null,
      "matchRunId": null,
      "matchCandidateId": null,
      "participantProfileId": null,
      "carrierOrganizationId": null,
      "routingMatrixRunId": null,
      "plannedPickupAt": null,
      "plannedDeliveryAt": null,
      "displayLabel": null,
      "hardBlockers": [
        {
          "code": "string",
          "labelKey": "string",
          "kind": "hard"
        }
      ],
      "scoreComponents": [
        {
          "code": "string",
          "labelKey": "string",
          "score": 1,
          "weight": 1,
          "severity": "positive"
        }
      ],
      "dispatchDraft": null,
      "decidedAt": null,
      "decidedByUserId": null
    }
  ]
}
404Run not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/optimizations/runs/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/optimizations/runs/{id}/override
Auth requiredoptimizations.decide

Override optimization run

Requires features: optimizations.decide

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "assignmentType": "dispatch_assignment",
  "vehicleId": null,
  "driverId": null,
  "trailerId": null,
  "participantProfileId": null,
  "matchCandidateId": null,
  "plannedPickupAt": null,
  "plannedDeliveryAt": null,
  "note": null
}

Responses

200Run overridden
Content-Type: application/json
{
  "id": "string",
  "runId": "string",
  "decisionStatus": "candidate",
  "dispatchDraft": null
}
404Run not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/optimizations/runs/:id/override" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"assignmentType\": \"dispatch_assignment\",
  \"vehicleId\": null,
  \"driverId\": null,
  \"trailerId\": null,
  \"participantProfileId\": null,
  \"matchCandidateId\": null,
  \"plannedPickupAt\": null,
  \"plannedDeliveryAt\": null,
  \"note\": null
}"
POST/api/freight/optimizations/runs/{id}/refresh
Auth requiredoptimizations.run

Refresh optimization run

Requires features: optimizations.run

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "allowFallback": true,
  "forceRefresh": true
}

Responses

200Optimization run refreshed
Content-Type: application/json
{
  "id": "string",
  "sourceType": "marketplace_shipment",
  "sourceId": "string",
  "sourceLabel": null,
  "status": "running",
  "providerId": "INTERNAL_FAST",
  "objective": "balanced",
  "candidateCount": 1,
  "acceptedCandidateId": null,
  "isCurrent": true,
  "confidenceScore": null,
  "sourceMode": null,
  "degradedReasonCode": null,
  "sensitiveEvidenceAvailable": true,
  "createdAt": "string",
  "updatedAt": "string",
  "summary": null,
  "candidates": [
    {
      "id": "string",
      "runId": "string",
      "assignmentType": "dispatch_assignment",
      "rank": 1,
      "score": 1,
      "confidenceScore": 1,
      "recommendation": "recommended",
      "decisionStatus": "candidate",
      "shipmentId": null,
      "matchRunId": null,
      "matchCandidateId": null,
      "participantProfileId": null,
      "carrierOrganizationId": null,
      "routingMatrixRunId": null,
      "plannedPickupAt": null,
      "plannedDeliveryAt": null,
      "displayLabel": null,
      "hardBlockers": [
        {
          "code": "string",
          "labelKey": "string",
          "kind": "hard"
        }
      ],
      "scoreComponents": [
        {
          "code": "string",
          "labelKey": "string",
          "score": 1,
          "weight": 1,
          "severity": "positive"
        }
      ],
      "dispatchDraft": null,
      "decidedAt": null,
      "decidedByUserId": null
    }
  ]
}
404Run not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/optimizations/runs/:id/refresh" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"allowFallback\": true,
  \"forceRefresh\": true
}"

Freight Payouts

Showing 20 of 23 endpoints
GET/api/freight/payouts/executions
Auth requiredpayouts.view

List payout executions

Requires features: payouts.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
searchqueryNoany
statusqueryNoany
reconciliationStatusqueryNoany
legalGateStatusqueryNoany
executionModequeryNoany
providerKeyqueryNoany
settlementPayoutRequestIdqueryNoany
carrierParticipantIdqueryNoany
currencyqueryNoany
includeSensitivequeryNoany
fromqueryNoany
toqueryNoany

Responses

200Payout executions returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "executionNumber": "string",
      "settlementPayoutRequestId": "string",
      "settlementRunId": null,
      "settlementEntryIds": [
        "string"
      ],
      "carrierParticipantId": "string",
      "carrierOrganizationId": null,
      "payoutAccountId": "string",
      "maskedAccount": "string",
      "providerKey": "string",
      "executionMode": "manual",
      "legalGateStatus": "not_required",
      "payoutLegalGateId": null,
      "legalGateSnapshot": null,
      "approvalReference": null,
      "status": "draft",
      "currency": "string",
      "totalAmount": "string",
      "providerBatchId": null,
      "providerPayoutId": null,
      "reconciliationStatus": "not_required",
      "attemptCount": 1,
      "nextRetryAt": null,
      "progressJobId": null,
      "partnerIntentId": null,
      "requestSnapshot": null,
      "legalReviewNote": null,
      "failureDetails": null,
      "manualNote": null,
      "approvedByUserId": null,
      "approvedAt": null,
      "revision": 1,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1,
  "pageInfo": {
    "hasNextPage": true
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/payouts/executions?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/payouts/executions
Auth requiredpayouts.manage

Create payout execution

Requires features: payouts.manage

Request body (application/json)

{
  "settlementPayoutRequestId": "string",
  "providerKey": "manual",
  "executionMode": "manual",
  "legalReviewNote": null,
  "manualNote": null
}

Responses

201Payout execution created
Content-Type: application/json
{
  "ok": true,
  "execution": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "executionNumber": "string",
    "settlementPayoutRequestId": "string",
    "settlementRunId": null,
    "settlementEntryIds": [
      "string"
    ],
    "carrierParticipantId": "string",
    "carrierOrganizationId": null,
    "payoutAccountId": "string",
    "maskedAccount": "string",
    "providerKey": "string",
    "executionMode": "manual",
    "legalGateStatus": "not_required",
    "payoutLegalGateId": null,
    "legalGateSnapshot": null,
    "approvalReference": null,
    "status": "draft",
    "currency": "string",
    "totalAmount": "string",
    "providerBatchId": null,
    "providerPayoutId": null,
    "reconciliationStatus": "not_required",
    "attemptCount": 1,
    "nextRetryAt": null,
    "progressJobId": null,
    "partnerIntentId": null,
    "requestSnapshot": null,
    "legalReviewNote": null,
    "failureDetails": null,
    "manualNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/executions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"settlementPayoutRequestId\": \"string\",
  \"providerKey\": \"manual\",
  \"executionMode\": \"manual\",
  \"legalReviewNote\": null,
  \"manualNote\": null
}"
GET/api/freight/payouts/executions/{id}
Auth requiredpayouts.view

Get payout execution

Requires features: payouts.view

Parameters

NameInRequiredSchemaDescription
idpathYesany
includeSensitivequeryNoany

Responses

200Payout execution returned
Content-Type: application/json
{
  "ok": true,
  "execution": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "executionNumber": "string",
    "settlementPayoutRequestId": "string",
    "settlementRunId": null,
    "settlementEntryIds": [
      "string"
    ],
    "carrierParticipantId": "string",
    "carrierOrganizationId": null,
    "payoutAccountId": "string",
    "maskedAccount": "string",
    "providerKey": "string",
    "executionMode": "manual",
    "legalGateStatus": "not_required",
    "payoutLegalGateId": null,
    "legalGateSnapshot": null,
    "approvalReference": null,
    "status": "draft",
    "currency": "string",
    "totalAmount": "string",
    "providerBatchId": null,
    "providerPayoutId": null,
    "reconciliationStatus": "not_required",
    "attemptCount": 1,
    "nextRetryAt": null,
    "progressJobId": null,
    "partnerIntentId": null,
    "requestSnapshot": null,
    "legalReviewNote": null,
    "failureDetails": null,
    "manualNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string",
    "attempts": [
      {
        "id": "string",
        "tenantId": "string",
        "organizationId": "string",
        "payoutExecutionId": "string",
        "attemptNumber": 1,
        "providerKey": "string",
        "status": "queued",
        "failureClassification": null,
        "failureCode": null,
        "providerStatus": null,
        "providerPayoutId": null,
        "providerBatchId": null,
        "requestSummary": null,
        "responseSummary": null,
        "sensitivePayload": null,
        "retryable": true,
        "startedAt": null,
        "finishedAt": null,
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "reconciliationItems": [
      {
        "id": "string",
        "tenantId": "string",
        "organizationId": "string",
        "payoutExecutionId": null,
        "payoutAttemptId": null,
        "sourceType": "provider_webhook",
        "providerKey": "string",
        "providerPayoutId": null,
        "providerBatchId": null,
        "amount": null,
        "currency": null,
        "status": "unmatched",
        "rawPayloadHash": null,
        "summary": null,
        "sensitivePayload": null,
        "resolutionNote": null,
        "importedByUserId": null,
        "matchedAt": null,
        "resolvedAt": null,
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "partnerIntents": [
      {
        "id": "string",
        "tenantId": "string",
        "organizationId": "string",
        "payoutExecutionId": "string",
        "intentType": "quickpay",
        "partnerKey": "string",
        "status": "intent_recorded",
        "advanceAmount": null,
        "feeAmount": null,
        "feeCurrency": null,
        "partnerReference": null,
        "termsSnapshot": null,
        "sensitiveTermsPayload": null,
        "reviewNote": null,
        "createdByUserId": null,
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/payouts/executions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/payouts/executions/{id}/cancel
Auth requiredpayouts.manage

Cancel payout execution

Requires features: payouts.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "reason": null,
  "note": null
}

Responses

200Payout execution returned
Content-Type: application/json
{
  "ok": true,
  "execution": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "executionNumber": "string",
    "settlementPayoutRequestId": "string",
    "settlementRunId": null,
    "settlementEntryIds": [
      "string"
    ],
    "carrierParticipantId": "string",
    "carrierOrganizationId": null,
    "payoutAccountId": "string",
    "maskedAccount": "string",
    "providerKey": "string",
    "executionMode": "manual",
    "legalGateStatus": "not_required",
    "payoutLegalGateId": null,
    "legalGateSnapshot": null,
    "approvalReference": null,
    "status": "draft",
    "currency": "string",
    "totalAmount": "string",
    "providerBatchId": null,
    "providerPayoutId": null,
    "reconciliationStatus": "not_required",
    "attemptCount": 1,
    "nextRetryAt": null,
    "progressJobId": null,
    "partnerIntentId": null,
    "requestSnapshot": null,
    "legalReviewNote": null,
    "failureDetails": null,
    "manualNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/executions/:id/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"reason\": null,
  \"note\": null
}"
POST/api/freight/payouts/executions/{id}/manual-success
Auth requiredpayouts.manage

Mark manual payout success

Requires features: payouts.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "providerPayoutId": null,
  "providerBatchId": null,
  "amount": null,
  "currency": null,
  "note": null
}

Responses

200Payout execution returned
Content-Type: application/json
{
  "ok": true,
  "execution": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "executionNumber": "string",
    "settlementPayoutRequestId": "string",
    "settlementRunId": null,
    "settlementEntryIds": [
      "string"
    ],
    "carrierParticipantId": "string",
    "carrierOrganizationId": null,
    "payoutAccountId": "string",
    "maskedAccount": "string",
    "providerKey": "string",
    "executionMode": "manual",
    "legalGateStatus": "not_required",
    "payoutLegalGateId": null,
    "legalGateSnapshot": null,
    "approvalReference": null,
    "status": "draft",
    "currency": "string",
    "totalAmount": "string",
    "providerBatchId": null,
    "providerPayoutId": null,
    "reconciliationStatus": "not_required",
    "attemptCount": 1,
    "nextRetryAt": null,
    "progressJobId": null,
    "partnerIntentId": null,
    "requestSnapshot": null,
    "legalReviewNote": null,
    "failureDetails": null,
    "manualNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/executions/:id/manual-success" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"providerPayoutId\": null,
  \"providerBatchId\": null,
  \"amount\": null,
  \"currency\": null,
  \"note\": null
}"
POST/api/freight/payouts/executions/{id}/mark-ready
Auth requiredpayouts.legal_review

Mark payout execution ready

Requires features: payouts.legal_review

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Payout execution returned
Content-Type: application/json
{
  "ok": true,
  "execution": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "executionNumber": "string",
    "settlementPayoutRequestId": "string",
    "settlementRunId": null,
    "settlementEntryIds": [
      "string"
    ],
    "carrierParticipantId": "string",
    "carrierOrganizationId": null,
    "payoutAccountId": "string",
    "maskedAccount": "string",
    "providerKey": "string",
    "executionMode": "manual",
    "legalGateStatus": "not_required",
    "payoutLegalGateId": null,
    "legalGateSnapshot": null,
    "approvalReference": null,
    "status": "draft",
    "currency": "string",
    "totalAmount": "string",
    "providerBatchId": null,
    "providerPayoutId": null,
    "reconciliationStatus": "not_required",
    "attemptCount": 1,
    "nextRetryAt": null,
    "progressJobId": null,
    "partnerIntentId": null,
    "requestSnapshot": null,
    "legalReviewNote": null,
    "failureDetails": null,
    "manualNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/executions/:id/mark-ready" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
POST/api/freight/payouts/executions/{id}/partner-intents
Auth requiredpayouts.partner_intents.manage

Record payout partner intent

Requires features: payouts.partner_intents.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "intentType": "quickpay",
  "partnerKey": "string",
  "advanceAmount": null,
  "feeAmount": null,
  "feeCurrency": null,
  "partnerReference": null,
  "termsSnapshot": null,
  "sensitiveTermsPayload": null,
  "reviewNote": null
}

Responses

201Payout partner intent returned
Content-Type: application/json
{
  "ok": true,
  "partnerIntent": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "payoutExecutionId": "string",
    "intentType": "quickpay",
    "partnerKey": "string",
    "status": "intent_recorded",
    "advanceAmount": null,
    "feeAmount": null,
    "feeCurrency": null,
    "partnerReference": null,
    "termsSnapshot": null,
    "sensitiveTermsPayload": null,
    "reviewNote": null,
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/executions/:id/partner-intents" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"intentType\": \"quickpay\",
  \"partnerKey\": \"string\",
  \"advanceAmount\": null,
  \"feeAmount\": null,
  \"feeCurrency\": null,
  \"partnerReference\": null,
  \"termsSnapshot\": null,
  \"sensitiveTermsPayload\": null,
  \"reviewNote\": null
}"
POST/api/freight/payouts/executions/{id}/queue
Auth requiredpayouts.manage

Queue payout execution

Requires features: payouts.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

202Payout execution queued
Content-Type: application/json
{
  "ok": true,
  "execution": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "executionNumber": "string",
    "settlementPayoutRequestId": "string",
    "settlementRunId": null,
    "settlementEntryIds": [
      "string"
    ],
    "carrierParticipantId": "string",
    "carrierOrganizationId": null,
    "payoutAccountId": "string",
    "maskedAccount": "string",
    "providerKey": "string",
    "executionMode": "manual",
    "legalGateStatus": "not_required",
    "payoutLegalGateId": null,
    "legalGateSnapshot": null,
    "approvalReference": null,
    "status": "draft",
    "currency": "string",
    "totalAmount": "string",
    "providerBatchId": null,
    "providerPayoutId": null,
    "reconciliationStatus": "not_required",
    "attemptCount": 1,
    "nextRetryAt": null,
    "progressJobId": null,
    "partnerIntentId": null,
    "requestSnapshot": null,
    "legalReviewNote": null,
    "failureDetails": null,
    "manualNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "progressJobId": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/executions/:id/queue" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/freight/payouts/executions/{id}/retry
Auth requiredpayouts.manage

Retry payout execution

Requires features: payouts.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

202Payout execution queued
Content-Type: application/json
{
  "ok": true,
  "execution": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "executionNumber": "string",
    "settlementPayoutRequestId": "string",
    "settlementRunId": null,
    "settlementEntryIds": [
      "string"
    ],
    "carrierParticipantId": "string",
    "carrierOrganizationId": null,
    "payoutAccountId": "string",
    "maskedAccount": "string",
    "providerKey": "string",
    "executionMode": "manual",
    "legalGateStatus": "not_required",
    "payoutLegalGateId": null,
    "legalGateSnapshot": null,
    "approvalReference": null,
    "status": "draft",
    "currency": "string",
    "totalAmount": "string",
    "providerBatchId": null,
    "providerPayoutId": null,
    "reconciliationStatus": "not_required",
    "attemptCount": 1,
    "nextRetryAt": null,
    "progressJobId": null,
    "partnerIntentId": null,
    "requestSnapshot": null,
    "legalReviewNote": null,
    "failureDetails": null,
    "manualNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "progressJobId": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/executions/:id/retry" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/freight/payouts/legal-gates/{id}/approve
Auth requiredpayouts.legal_review

Approve payout legal gate

Requires features: payouts.legal_review

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "legalApprovalReference": null,
  "financialApprovalReference": null,
  "providerApprovalReference": null,
  "legalReviewNote": null,
  "financialReviewNote": null,
  "providerReviewNote": null,
  "validFrom": null,
  "validUntil": null
}

Responses

200Payout legal gate returned
Content-Type: application/json
{
  "ok": true,
  "legalGate": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "gateNumber": "string",
    "providerKey": "string",
    "integrationId": null,
    "currency": "string",
    "status": "blocked",
    "legalReviewStatus": "pending",
    "financialReviewStatus": "pending",
    "providerReviewStatus": "pending",
    "legalApprovalReference": null,
    "financialApprovalReference": null,
    "providerApprovalReference": null,
    "legalReviewNote": null,
    "financialReviewNote": null,
    "providerReviewNote": null,
    "suspensionNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "validFrom": null,
    "validUntil": null,
    "integrationStateSnapshot": null,
    "isActive": true,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/legal-gates/:id/approve" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"legalApprovalReference\": null,
  \"financialApprovalReference\": null,
  \"providerApprovalReference\": null,
  \"legalReviewNote\": null,
  \"financialReviewNote\": null,
  \"providerReviewNote\": null,
  \"validFrom\": null,
  \"validUntil\": null
}"
POST/api/freight/payouts/legal-gates/{id}/reopen
Auth requiredpayouts.legal_review

Reopen payout legal gate

Requires features: payouts.legal_review

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Payout legal gate returned
Content-Type: application/json
{
  "ok": true,
  "legalGate": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "gateNumber": "string",
    "providerKey": "string",
    "integrationId": null,
    "currency": "string",
    "status": "blocked",
    "legalReviewStatus": "pending",
    "financialReviewStatus": "pending",
    "providerReviewStatus": "pending",
    "legalApprovalReference": null,
    "financialApprovalReference": null,
    "providerApprovalReference": null,
    "legalReviewNote": null,
    "financialReviewNote": null,
    "providerReviewNote": null,
    "suspensionNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "validFrom": null,
    "validUntil": null,
    "integrationStateSnapshot": null,
    "isActive": true,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/legal-gates/:id/reopen" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
POST/api/freight/payouts/legal-gates/{id}/suspend
Auth requiredpayouts.legal_review

Suspend payout legal gate

Requires features: payouts.legal_review

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": "string"
}

Responses

200Payout legal gate returned
Content-Type: application/json
{
  "ok": true,
  "legalGate": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "gateNumber": "string",
    "providerKey": "string",
    "integrationId": null,
    "currency": "string",
    "status": "blocked",
    "legalReviewStatus": "pending",
    "financialReviewStatus": "pending",
    "providerReviewStatus": "pending",
    "legalApprovalReference": null,
    "financialApprovalReference": null,
    "providerApprovalReference": null,
    "legalReviewNote": null,
    "financialReviewNote": null,
    "providerReviewNote": null,
    "suspensionNote": null,
    "approvedByUserId": null,
    "approvedAt": null,
    "validFrom": null,
    "validUntil": null,
    "integrationStateSnapshot": null,
    "isActive": true,
    "revision": 1,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/legal-gates/:id/suspend" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": \"string\"
}"
GET/api/freight/payouts/partner-intents
Auth requiredpayouts.view

List payout partner intents

Requires features: payouts.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
searchqueryNoany
payoutExecutionIdqueryNoany
intentTypequeryNoany
statusqueryNoany
partnerKeyqueryNoany
includeSensitivequeryNoany

Responses

200Payout partner intents returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "payoutExecutionId": "string",
      "intentType": "quickpay",
      "partnerKey": "string",
      "status": "intent_recorded",
      "advanceAmount": null,
      "feeAmount": null,
      "feeCurrency": null,
      "partnerReference": null,
      "termsSnapshot": null,
      "sensitiveTermsPayload": null,
      "reviewNote": null,
      "createdByUserId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1,
  "pageInfo": {
    "hasNextPage": true
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/payouts/partner-intents?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/payouts/partner-intents/{id}/cancel
Auth requiredpayouts.partner_intents.manage

Cancel payout partner intent

Requires features: payouts.partner_intents.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Payout partner intent returned
Content-Type: application/json
{
  "ok": true,
  "partnerIntent": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "payoutExecutionId": "string",
    "intentType": "quickpay",
    "partnerKey": "string",
    "status": "intent_recorded",
    "advanceAmount": null,
    "feeAmount": null,
    "feeCurrency": null,
    "partnerReference": null,
    "termsSnapshot": null,
    "sensitiveTermsPayload": null,
    "reviewNote": null,
    "createdByUserId": null,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/partner-intents/:id/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
GET/api/freight/payouts/providers
Auth requiredpayouts.view

List payout providers

Requires features: payouts.view

Parameters

NameInRequiredSchemaDescription
providerKeyqueryNoany
executionModequeryNoany
currencyqueryNoany

Responses

200Payout providers returned
Content-Type: application/json
{
  "data": [
    {
      "providerKey": "string",
      "label": "string",
      "configuredAdapter": true,
      "payoutConfig": null
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/payouts/providers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/payouts/reconciliation
Auth requiredpayouts.view

List payout reconciliation items

Requires features: payouts.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
searchqueryNoany
statusqueryNoany
sourceTypequeryNoany
providerKeyqueryNoany
payoutExecutionIdqueryNoany
includeSensitivequeryNoany
fromqueryNoany
toqueryNoany

Responses

200Payout reconciliation items returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "payoutExecutionId": null,
      "payoutAttemptId": null,
      "sourceType": "provider_webhook",
      "providerKey": "string",
      "providerPayoutId": null,
      "providerBatchId": null,
      "amount": null,
      "currency": null,
      "status": "unmatched",
      "rawPayloadHash": null,
      "summary": null,
      "sensitivePayload": null,
      "resolutionNote": null,
      "importedByUserId": null,
      "matchedAt": null,
      "resolvedAt": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1,
  "pageInfo": {
    "hasNextPage": true
  }
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/payouts/reconciliation?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/payouts/reconciliation/{id}/resolve
Auth requiredpayouts.manage

Resolve payout reconciliation item

Requires features: payouts.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "resolution": "matched",
  "note": "string"
}

Responses

200Payout reconciliation item resolved
Content-Type: application/json
{
  "ok": true,
  "item": {
    "id": "string",
    "tenantId": "string",
    "organizationId": "string",
    "payoutExecutionId": null,
    "payoutAttemptId": null,
    "sourceType": "provider_webhook",
    "providerKey": "string",
    "providerPayoutId": null,
    "providerBatchId": null,
    "amount": null,
    "currency": null,
    "status": "unmatched",
    "rawPayloadHash": null,
    "summary": null,
    "sensitivePayload": null,
    "resolutionNote": null,
    "importedByUserId": null,
    "matchedAt": null,
    "resolvedAt": null,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/payouts/reconciliation/:id/resolve" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"resolution\": \"matched\",
  \"note\": \"string\"
}"

Freight Pricing

Showing 16 of 16 endpoints
GET/api/freight/pricing/charge-codes
Auth requiredpricing.view

List chargecodes

Returns a paginated collection of chargecodes scoped to the authenticated organization. Requires features: pricing.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
categoryqueryNoany
isActivequeryNoany

Responses

200Paginated chargecodes
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": null,
      "organizationId": null,
      "code": "string",
      "label": "string",
      "category": "base_freight",
      "defaultUnitCode": "shipment",
      "defaultTaxRate": null,
      "isTaxable": true,
      "isActive": true,
      "sortOrder": 1,
      "description": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/pricing/charge-codes?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/pricing/charge-codes
Auth requiredpricing.manage_charge_codes

Create chargecode

Creates a freight pricing charge code. Requires features: pricing.manage_charge_codes

Request body (application/json)

{
  "tenantId": "string",
  "organizationId": "string",
  "code": "string",
  "label": "string",
  "category": "base_freight",
  "defaultUnitCode": "shipment",
  "defaultTaxRate": null,
  "isTaxable": true,
  "isActive": true,
  "sortOrder": 100,
  "description": null
}

Responses

201ChargeCode created
Content-Type: application/json
{
  "id": null,
  "code": null
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/pricing/charge-codes" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"string\",
  \"organizationId\": \"string\",
  \"code\": \"string\",
  \"label\": \"string\",
  \"category\": \"base_freight\",
  \"defaultUnitCode\": \"shipment\",
  \"defaultTaxRate\": null,
  \"isTaxable\": true,
  \"isActive\": true,
  \"sortOrder\": 100,
  \"description\": null
}"
PUT/api/freight/pricing/charge-codes
Auth requiredpricing.manage_charge_codes

Update chargecode

Updates a freight pricing charge code. Requires features: pricing.manage_charge_codes

Request body (application/json)

{
  "defaultTaxRate": null,
  "isTaxable": true,
  "isActive": true,
  "sortOrder": 100,
  "description": null,
  "id": "string"
}

Responses

200ChargeCode updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/freight/pricing/charge-codes" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"defaultTaxRate\": null,
  \"isTaxable\": true,
  \"isActive\": true,
  \"sortOrder\": 100,
  \"description\": null,
  \"id\": \"string\"
}"
DELETE/api/freight/pricing/charge-codes
Auth requiredpricing.manage_charge_codes

Delete chargecode

Soft-deletes or deactivates a freight pricing charge code. Requires features: pricing.manage_charge_codes

Request body (application/json)

{
  "id": "string"
}

Responses

200ChargeCode deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/freight/pricing/charge-codes" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\"
}"
GET/api/freight/pricing/contract-rates
Auth requiredpricing.view

List contractrates

Returns a paginated collection of contractrates scoped to the authenticated organization. Requires features: pricing.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
searchqueryNoany
idsqueryNoanyComma-separated list of record UUIDs to filter by (max 200).
cursorqueryNoany
statusqueryNoany
modequeryNoany
cargoSegmentqueryNoany
laneIdqueryNoany
carrierParticipantIdqueryNoany
carrierOrganizationIdqueryNoany
currencyqueryNoany
effectiveOnqueryNoany

Responses

200Paginated contractrates
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": null,
      "organizationId": null,
      "rateNumber": "string",
      "status": "draft",
      "sourceType": "internal",
      "priority": 1,
      "shipperOrganizationId": null,
      "carrierOrganizationId": null,
      "carrierParticipantId": null,
      "laneId": null,
      "originRegionId": null,
      "destinationRegionId": null,
      "mode": "road",
      "cargoSegment": null,
      "equipmentType": null,
      "currency": "string",
      "effectiveFrom": null,
      "effectiveTo": null,
      "minWeightTons": null,
      "maxWeightTons": null,
      "minDistanceKm": null,
      "maxDistanceKm": null,
      "minChargeAmount": null,
      "maxChargeAmount": null,
      "createdByUserId": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/pricing/contract-rates?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/pricing/contract-rates
Auth requiredpricing.manage_contract_rates

Create contractrate

Creates a freight pricing contract rate and its ordered lines. Requires features: pricing.manage_contract_rates

Request body (application/json)

{
  "tenantId": "string",
  "organizationId": "string",
  "rateNumber": "string",
  "status": "draft",
  "sourceType": "internal",
  "priority": 100,
  "shipperOrganizationId": null,
  "carrierOrganizationId": null,
  "carrierParticipantId": null,
  "laneId": null,
  "originRegionId": null,
  "destinationRegionId": null,
  "mode": "road",
  "cargoSegment": null,
  "equipmentType": null,
  "currency": "string",
  "effectiveFrom": "string",
  "effectiveTo": null,
  "minWeightTons": null,
  "maxWeightTons": null,
  "minDistanceKm": null,
  "maxDistanceKm": null,
  "minChargeAmount": null,
  "maxChargeAmount": null,
  "termsText": null,
  "internalNotes": null,
  "externalReference": null,
  "createdByUserId": "string",
  "lines": []
}

Responses

201ContractRate created
Content-Type: application/json
{
  "id": null,
  "rateNumber": null,
  "status": null
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/pricing/contract-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"string\",
  \"organizationId\": \"string\",
  \"rateNumber\": \"string\",
  \"status\": \"draft\",
  \"sourceType\": \"internal\",
  \"priority\": 100,
  \"shipperOrganizationId\": null,
  \"carrierOrganizationId\": null,
  \"carrierParticipantId\": null,
  \"laneId\": null,
  \"originRegionId\": null,
  \"destinationRegionId\": null,
  \"mode\": \"road\",
  \"cargoSegment\": null,
  \"equipmentType\": null,
  \"currency\": \"string\",
  \"effectiveFrom\": \"string\",
  \"effectiveTo\": null,
  \"minWeightTons\": null,
  \"maxWeightTons\": null,
  \"minDistanceKm\": null,
  \"maxDistanceKm\": null,
  \"minChargeAmount\": null,
  \"maxChargeAmount\": null,
  \"termsText\": null,
  \"internalNotes\": null,
  \"externalReference\": null,
  \"createdByUserId\": \"string\",
  \"lines\": []
}"
PUT/api/freight/pricing/contract-rates
Auth requiredpricing.manage_contract_rates

Update contractrate

Updates a freight pricing contract rate and optionally replaces all lines. Requires features: pricing.manage_contract_rates

Request body (application/json)

{
  "status": "draft",
  "sourceType": "internal",
  "priority": 100,
  "shipperOrganizationId": null,
  "carrierOrganizationId": null,
  "carrierParticipantId": null,
  "laneId": null,
  "originRegionId": null,
  "destinationRegionId": null,
  "cargoSegment": null,
  "equipmentType": null,
  "effectiveTo": null,
  "minWeightTons": null,
  "maxWeightTons": null,
  "minDistanceKm": null,
  "maxDistanceKm": null,
  "minChargeAmount": null,
  "maxChargeAmount": null,
  "termsText": null,
  "internalNotes": null,
  "externalReference": null,
  "id": "string"
}

Responses

200ContractRate updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/freight/pricing/contract-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"status\": \"draft\",
  \"sourceType\": \"internal\",
  \"priority\": 100,
  \"shipperOrganizationId\": null,
  \"carrierOrganizationId\": null,
  \"carrierParticipantId\": null,
  \"laneId\": null,
  \"originRegionId\": null,
  \"destinationRegionId\": null,
  \"cargoSegment\": null,
  \"equipmentType\": null,
  \"effectiveTo\": null,
  \"minWeightTons\": null,
  \"maxWeightTons\": null,
  \"minDistanceKm\": null,
  \"maxDistanceKm\": null,
  \"minChargeAmount\": null,
  \"maxChargeAmount\": null,
  \"termsText\": null,
  \"internalNotes\": null,
  \"externalReference\": null,
  \"id\": \"string\"
}"
DELETE/api/freight/pricing/contract-rates
Auth requiredpricing.manage_contract_rates

Delete contractrate

Soft-deletes a freight pricing contract rate and its lines. Requires features: pricing.manage_contract_rates

Request body (application/json)

{
  "id": "string"
}

Responses

200ContractRate deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/freight/pricing/contract-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"string\"
}"
GET/api/freight/pricing/contract-rates/{id}
Auth requiredpricing.view

Get contract rate detail with lines

Requires features: pricing.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Contract rate returned
Content-Type: application/json
{
  "id": "string",
  "tenantId": null,
  "organizationId": null,
  "rateNumber": "string",
  "status": "draft",
  "sourceType": "internal",
  "priority": 1,
  "shipperOrganizationId": null,
  "carrierOrganizationId": null,
  "carrierParticipantId": null,
  "laneId": null,
  "originRegionId": null,
  "destinationRegionId": null,
  "mode": "road",
  "cargoSegment": null,
  "equipmentType": null,
  "currency": "string",
  "effectiveFrom": null,
  "effectiveTo": null,
  "minWeightTons": null,
  "maxWeightTons": null,
  "minDistanceKm": null,
  "maxDistanceKm": null,
  "minChargeAmount": null,
  "maxChargeAmount": null,
  "createdByUserId": null,
  "createdAt": null,
  "updatedAt": null
}
404Contract rate not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/pricing/contract-rates/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/pricing/contract-rates/{id}/activate
Auth requiredpricing.manage_contract_rates

Activate freight pricing contract rate

Requires features: pricing.manage_contract_rates

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "reasonCode": null,
  "reasonText": null
}

Responses

200Contract rate activated
Content-Type: application/json
{
  "id": "string",
  "status": "draft"
}
404Contract rate not found
Content-Type: application/json
"string"
422Invalid lifecycle transition
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/pricing/contract-rates/:id/activate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"reasonCode\": null,
  \"reasonText\": null
}"
POST/api/freight/pricing/contract-rates/{id}/expire
Auth requiredpricing.manage_contract_rates

Expire freight pricing contract rate

Requires features: pricing.manage_contract_rates

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "reasonCode": null,
  "reasonText": null
}

Responses

200Contract rate expired
Content-Type: application/json
{
  "id": "string",
  "status": "draft"
}
404Contract rate not found
Content-Type: application/json
"string"
422Invalid lifecycle transition
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/pricing/contract-rates/:id/expire" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"reasonCode\": null,
  \"reasonText\": null
}"
POST/api/freight/pricing/contract-rates/{id}/suspend
Auth requiredpricing.manage_contract_rates

Suspend freight pricing contract rate

Requires features: pricing.manage_contract_rates

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "reasonCode": null,
  "reasonText": null
}

Responses

200Contract rate suspended
Content-Type: application/json
{
  "id": "string",
  "status": "draft"
}
404Contract rate not found
Content-Type: application/json
"string"
422Invalid lifecycle transition
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/pricing/contract-rates/:id/suspend" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"reasonCode\": null,
  \"reasonText\": null
}"
GET/api/freight/pricing/estimates
Auth requiredpricing.view

List freight spot price estimates

Requires features: pricing.view

Parameters

NameInRequiredSchemaDescription
pageSizequeryNoany
cursorqueryNoany
shipmentIdqueryNoany
proposalIdqueryNoany
laneIdqueryNoany
statusqueryNoany
modequeryNoany
cargoSegmentqueryNoany
createdFromqueryNoany
createdToqueryNoany

Responses

200Paginated spot price estimates
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": null,
      "organizationId": null,
      "estimateNumber": "string",
      "status": "calculated",
      "shipmentId": null,
      "proposalId": null,
      "contractRateId": null,
      "laneId": null,
      "mode": "road",
      "cargoSegment": "container_iso",
      "currency": "string",
      "netAmount": "string",
      "taxAmount": "string",
      "totalAmount": "string",
      "confidenceScore": null,
      "rateVersionHash": null,
      "expiresAt": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/pricing/estimates?pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/pricing/estimates/{id}
Auth requiredpricing.view

Get freight spot price estimate detail

Requires features: pricing.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Spot price estimate returned
Content-Type: application/json
{
  "id": "string",
  "tenantId": null,
  "organizationId": null,
  "estimateNumber": "string",
  "status": "calculated",
  "shipmentId": null,
  "proposalId": null,
  "contractRateId": null,
  "laneId": null,
  "mode": "road",
  "cargoSegment": "container_iso",
  "currency": "string",
  "netAmount": "string",
  "taxAmount": "string",
  "totalAmount": "string",
  "confidenceScore": null,
  "rateVersionHash": null,
  "expiresAt": null,
  "createdAt": null,
  "updatedAt": null,
  "lines": [
    {
      "chargeCodeId": null,
      "chargeCode": "string",
      "sourceType": "contract_rate",
      "sourceId": null,
      "quantity": "string",
      "unitCode": "string",
      "unitPrice": "string",
      "netAmount": "string",
      "taxAmount": "string",
      "totalAmount": "string",
      "explanationCode": "string"
    }
  ]
}
404Spot price estimate not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/pricing/estimates/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/pricing/estimates/{id}/expire
Auth requiredpricing.manage_estimates

Expire freight spot price estimate

Requires features: pricing.manage_estimates

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{}

Responses

200Spot price estimate expired
Content-Type: application/json
{
  "id": "string",
  "status": "string"
}
404Spot price estimate not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/pricing/estimates/:id/expire" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"
POST/api/freight/pricing/estimates/quote
Auth requiredpricing.quote_estimates

Quote a freight spot price estimate

Requires features: pricing.quote_estimates

Request body (application/json)

{
  "tenantId": "string",
  "organizationId": "string",
  "actorUserId": null,
  "shipmentId": null,
  "laneId": null,
  "originRegionId": null,
  "destinationRegionId": null,
  "mode": "road",
  "cargoSegment": "container_iso",
  "equipmentType": null,
  "carrierParticipantId": null,
  "carrierOrganizationId": null,
  "shipperOrganizationId": null,
  "weightTons": null,
  "volumeM3": null,
  "unitCount": null,
  "distanceKm": null,
  "durationMinutes": null,
  "requestedPickupAt": null,
  "currency": "string",
  "saveSnapshot": true
}

Responses

200Spot price estimate quoted
Content-Type: application/json
{
  "estimateId": null,
  "status": "calculated",
  "currency": "string",
  "netAmount": "string",
  "taxAmount": "string",
  "totalAmount": "string",
  "confidenceScore": null,
  "selectedContractRateId": null,
  "rateVersionHash": null,
  "selectedLaneId": null,
  "distanceKm": null,
  "durationMinutes": null,
  "lines": [
    {
      "chargeCodeId": null,
      "chargeCode": "string",
      "sourceType": "contract_rate",
      "sourceId": null,
      "quantity": "string",
      "unitCode": "string",
      "unitPrice": "string",
      "netAmount": "string",
      "taxAmount": "string",
      "totalAmount": "string",
      "explanationCode": "string"
    }
  ],
  "reasons": [
    {
      "code": "contract_rate_matched",
      "messageKey": "string"
    }
  ]
}
400Invalid quote payload
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/pricing/estimates/quote" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"tenantId\": \"string\",
  \"organizationId\": \"string\",
  \"actorUserId\": null,
  \"shipmentId\": null,
  \"laneId\": null,
  \"originRegionId\": null,
  \"destinationRegionId\": null,
  \"mode\": \"road\",
  \"cargoSegment\": \"container_iso\",
  \"equipmentType\": null,
  \"carrierParticipantId\": null,
  \"carrierOrganizationId\": null,
  \"shipperOrganizationId\": null,
  \"weightTons\": null,
  \"volumeM3\": null,
  \"unitCount\": null,
  \"distanceKm\": null,
  \"durationMinutes\": null,
  \"requestedPickupAt\": null,
  \"currency\": \"string\",
  \"saveSnapshot\": true
}"

Freight Reputation

Showing 6 of 6 endpoints
POST/api/freight/reputation/evaluate
Auth requiredreputation.view

Evaluate carrier reputation

Requires features: reputation.view

Responses

200Evaluation returned
Content-Type: application/json
{
  "participantProfileId": "string",
  "carrierOrganizationId": null,
  "laneId": null,
  "laneFingerprint": null,
  "score": null,
  "grade": null,
  "confidenceScore": 1,
  "accessTier": "trusted",
  "calculationVersion": "string",
  "calculatedAt": null,
  "reasons": [
    {
      "code": "strong_on_time_history",
      "severity": "positive",
      "messageKey": "string"
    }
  ]
}
400Invalid payload
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/reputation/evaluate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/reputation/lane-scores
Auth requiredreputation.view

List lane scores

Requires features: reputation.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
viewqueryNoany
idsqueryNoany
participantProfileIdqueryNoany
carrierOrganizationIdqueryNoany
laneIdqueryNoany
laneFingerprintqueryNoany
modequeryNoany
cargoSegmentqueryNoany
windowCodequeryNoany
gradequeryNoany
accessTierqueryNoany

Responses

200Lane scores returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "participantProfileId": "string",
      "participantLabel": null,
      "participantType": null,
      "customerEntityId": null,
      "customerDisplayName": null,
      "carrierOrganizationId": null,
      "laneId": null,
      "laneFingerprint": "string",
      "mode": null,
      "cargoSegment": null,
      "windowCode": "rolling_90d",
      "periodStart": null,
      "periodEnd": "string",
      "score": null,
      "grade": null,
      "confidenceScore": 1,
      "accessTier": "trusted",
      "completedShipmentCount": 1,
      "completedShipmentCount90d": 1,
      "totalTons": 1,
      "onTimeDeliveryPct": null,
      "avgTransitHours": null,
      "calculationVersion": "string",
      "calculatedAt": null
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1
}
400Invalid query
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/reputation/lane-scores?page=1&pageSize=25&view=history" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/reputation/lane-scores/{id}
Auth requiredreputation.view

Get lane score detail

Requires features: reputation.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Lane score returned
Content-Type: application/json
{
  "id": "string",
  "participantProfileId": "string",
  "participantLabel": null,
  "participantType": null,
  "customerEntityId": null,
  "customerDisplayName": null,
  "carrierOrganizationId": null,
  "laneId": null,
  "laneFingerprint": "string",
  "mode": null,
  "cargoSegment": null,
  "windowCode": "rolling_90d",
  "periodStart": null,
  "periodEnd": "string",
  "score": null,
  "grade": null,
  "confidenceScore": 1,
  "accessTier": "trusted",
  "completedShipmentCount": 1,
  "completedShipmentCount90d": 1,
  "totalTons": 1,
  "onTimeDeliveryPct": null,
  "avgTransitHours": null,
  "calculationVersion": "string",
  "calculatedAt": null,
  "factors": [
    {
      "factor": "string",
      "score": 1,
      "weight": 1,
      "value": null,
      "denominator": null
    }
  ],
  "reasons": [
    {
      "code": "strong_on_time_history",
      "severity": "positive",
      "messageKey": "string"
    }
  ],
  "sourceSnapshot": null,
  "internalNotes": null
}
404Lane score not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/reputation/lane-scores/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/reputation/recalculate
Auth requiredreputation.recalculate

Start recalculation

Requires features: reputation.recalculate

Responses

202Recalculation started
Content-Type: application/json
{
  "ok": true,
  "progressJobId": "string"
}
400Invalid payload
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/reputation/recalculate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/reputation/scorecards
Auth requiredreputation.view

List scorecards

Requires features: reputation.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
viewqueryNoany
idsqueryNoany
participantProfileIdqueryNoany
carrierOrganizationIdqueryNoany
windowCodequeryNoany
gradequeryNoany
accessTierqueryNoany
minScorequeryNoany
maxScorequeryNoany

Responses

200Scorecards returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "participantProfileId": "string",
      "participantLabel": null,
      "participantType": null,
      "customerEntityId": null,
      "customerDisplayName": null,
      "carrierOrganizationId": null,
      "windowCode": "rolling_90d",
      "periodStart": null,
      "periodEnd": "string",
      "score": null,
      "grade": null,
      "confidenceScore": 1,
      "accessTier": "trusted",
      "completedShipmentCount": 1,
      "comparableOnTimeCount": 1,
      "onTimeShipmentCount": 1,
      "cancelledShipmentCount": 1,
      "documentRequiredCount": 1,
      "documentValidCount": 1,
      "documentExpiredCount": 1,
      "calculationVersion": "string",
      "calculatedAt": null
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1
}
400Invalid query
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/reputation/scorecards?page=1&pageSize=25&view=history" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/reputation/scorecards/{id}
Auth requiredreputation.view

Get scorecard detail

Requires features: reputation.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Scorecard returned
Content-Type: application/json
{
  "id": "string",
  "participantProfileId": "string",
  "participantLabel": null,
  "participantType": null,
  "customerEntityId": null,
  "customerDisplayName": null,
  "carrierOrganizationId": null,
  "windowCode": "rolling_90d",
  "periodStart": null,
  "periodEnd": "string",
  "score": null,
  "grade": null,
  "confidenceScore": 1,
  "accessTier": "trusted",
  "completedShipmentCount": 1,
  "comparableOnTimeCount": 1,
  "onTimeShipmentCount": 1,
  "cancelledShipmentCount": 1,
  "documentRequiredCount": 1,
  "documentValidCount": 1,
  "documentExpiredCount": 1,
  "calculationVersion": "string",
  "calculatedAt": null,
  "factors": [
    {
      "factor": "string",
      "score": 1,
      "weight": 1,
      "value": null,
      "denominator": null
    }
  ],
  "reasons": [
    {
      "code": "strong_on_time_history",
      "severity": "positive",
      "messageKey": "string"
    }
  ],
  "sourceSnapshot": null,
  "internalNotes": null
}
404Scorecard not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/reputation/scorecards/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Freight Settlement

Showing 19 of 19 endpoints
GET/api/freight/settlement/entries
Auth requiredsettlement.view

List settlement entries

Requires features: settlement.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
searchqueryNoany
runIdqueryNoany
payoutRequestIdqueryNoany
statusqueryNoany
carrierParticipantIdqueryNoany
marketplaceShipmentIdqueryNoany
sourceShipmentIdqueryNoany
gateCodequeryNoany
fromqueryNoany
toqueryNoany
currencyqueryNoany

Responses

200Settlement entries returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "runId": "string",
      "payoutRequestId": null,
      "entryNumber": "string",
      "status": "eligible",
      "sourceShipmentId": "string",
      "marketplaceShipmentId": "string",
      "sourceProposalId": "string",
      "marketplaceProposalId": "string",
      "sourcePricingEstimateId": null,
      "carrierParticipantId": "string",
      "carrierOrganizationId": null,
      "currency": "string",
      "grossAmount": "string",
      "netAmount": null,
      "taxAmount": null,
      "amountSource": "string",
      "gateFailures": null,
      "holdReasonCode": null,
      "holdNote": null,
      "releasedAt": null,
      "releaseNote": null,
      "cancelledAt": null,
      "cancelNote": null,
      "snapshot": null,
      "revision": 1,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/settlement/entries?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/settlement/entries/{id}
Auth requiredsettlement.view

Get settlement entry

Requires features: settlement.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Settlement entry returned
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": "string",
  "payoutRequestId": null,
  "entryNumber": "string",
  "status": "eligible",
  "sourceShipmentId": "string",
  "marketplaceShipmentId": "string",
  "sourceProposalId": "string",
  "marketplaceProposalId": "string",
  "sourcePricingEstimateId": null,
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "currency": "string",
  "grossAmount": "string",
  "netAmount": null,
  "taxAmount": null,
  "amountSource": "string",
  "gateFailures": null,
  "holdReasonCode": null,
  "holdNote": null,
  "releasedAt": null,
  "releaseNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "snapshot": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}
404Settlement entry not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/settlement/entries/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/settlement/entries/{id}/cancel
Auth requiredsettlement.hold

Cancel settlement entry

Requires features: settlement.hold

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Settlement entry cancelled
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": "string",
  "payoutRequestId": null,
  "entryNumber": "string",
  "status": "eligible",
  "sourceShipmentId": "string",
  "marketplaceShipmentId": "string",
  "sourceProposalId": "string",
  "marketplaceProposalId": "string",
  "sourcePricingEstimateId": null,
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "currency": "string",
  "grossAmount": "string",
  "netAmount": null,
  "taxAmount": null,
  "amountSource": "string",
  "gateFailures": null,
  "holdReasonCode": null,
  "holdNote": null,
  "releasedAt": null,
  "releaseNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "snapshot": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/entries/:id/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
POST/api/freight/settlement/entries/{id}/hold
Auth requiredsettlement.hold

Hold settlement entry

Requires features: settlement.hold

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "reasonCode": "manual_hold",
  "note": null
}

Responses

200Settlement entry held
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": "string",
  "payoutRequestId": null,
  "entryNumber": "string",
  "status": "eligible",
  "sourceShipmentId": "string",
  "marketplaceShipmentId": "string",
  "sourceProposalId": "string",
  "marketplaceProposalId": "string",
  "sourcePricingEstimateId": null,
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "currency": "string",
  "grossAmount": "string",
  "netAmount": null,
  "taxAmount": null,
  "amountSource": "string",
  "gateFailures": null,
  "holdReasonCode": null,
  "holdNote": null,
  "releasedAt": null,
  "releaseNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "snapshot": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/entries/:id/hold" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"reasonCode\": \"manual_hold\",
  \"note\": null
}"
POST/api/freight/settlement/entries/{id}/release
Auth requiredsettlement.release

Release settlement entry

Requires features: settlement.release

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Settlement entry released
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": "string",
  "payoutRequestId": null,
  "entryNumber": "string",
  "status": "eligible",
  "sourceShipmentId": "string",
  "marketplaceShipmentId": "string",
  "sourceProposalId": "string",
  "marketplaceProposalId": "string",
  "sourcePricingEstimateId": null,
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "currency": "string",
  "grossAmount": "string",
  "netAmount": null,
  "taxAmount": null,
  "amountSource": "string",
  "gateFailures": null,
  "holdReasonCode": null,
  "holdNote": null,
  "releasedAt": null,
  "releaseNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "snapshot": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/entries/:id/release" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
GET/api/freight/settlement/payout-requests
Auth requiredsettlement.view

List payout requests

Requires features: settlement.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
searchqueryNoany
statusqueryNoany
runIdqueryNoany
carrierParticipantIdqueryNoany
currencyqueryNoany
fromqueryNoany
toqueryNoany
exportBatchIdqueryNoany

Responses

200Payout requests returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "runId": null,
      "requestNumber": "string",
      "status": "prepared",
      "carrierParticipantId": "string",
      "carrierOrganizationId": null,
      "payoutAccountId": "string",
      "maskedAccount": "string",
      "currency": "string",
      "totalAmount": "string",
      "entryIds": [
        "string"
      ],
      "accountSnapshot": null,
      "exportBatchId": null,
      "exportedAt": null,
      "exportNote": null,
      "holdReasonCode": null,
      "holdNote": null,
      "cancelledAt": null,
      "cancelNote": null,
      "revision": 1,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/settlement/payout-requests?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/settlement/payout-requests/{id}
Auth requiredsettlement.view

Get payout request

Requires features: settlement.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Payout request returned
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": null,
  "requestNumber": "string",
  "status": "prepared",
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "payoutAccountId": "string",
  "maskedAccount": "string",
  "currency": "string",
  "totalAmount": "string",
  "entryIds": [
    "string"
  ],
  "accountSnapshot": null,
  "exportBatchId": null,
  "exportedAt": null,
  "exportNote": null,
  "holdReasonCode": null,
  "holdNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}
404Payout request not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/settlement/payout-requests/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/settlement/payout-requests/{id}/cancel
Auth requiredsettlement.hold

Cancel payout request

Requires features: settlement.hold

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Payout request cancelled
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": null,
  "requestNumber": "string",
  "status": "prepared",
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "payoutAccountId": "string",
  "maskedAccount": "string",
  "currency": "string",
  "totalAmount": "string",
  "entryIds": [
    "string"
  ],
  "accountSnapshot": null,
  "exportBatchId": null,
  "exportedAt": null,
  "exportNote": null,
  "holdReasonCode": null,
  "holdNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/payout-requests/:id/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
POST/api/freight/settlement/payout-requests/{id}/export
Auth requiredsettlement.export

Mark payout request exported

Requires features: settlement.export

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "exportBatchId": "string",
  "note": null
}

Responses

200Payout request exported
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": null,
  "requestNumber": "string",
  "status": "prepared",
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "payoutAccountId": "string",
  "maskedAccount": "string",
  "currency": "string",
  "totalAmount": "string",
  "entryIds": [
    "string"
  ],
  "accountSnapshot": null,
  "exportBatchId": null,
  "exportedAt": null,
  "exportNote": null,
  "holdReasonCode": null,
  "holdNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/payout-requests/:id/export" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"exportBatchId\": \"string\",
  \"note\": null
}"
POST/api/freight/settlement/payout-requests/{id}/hold
Auth requiredsettlement.hold

Hold payout request

Requires features: settlement.hold

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "reasonCode": "manual_hold",
  "note": null
}

Responses

200Payout request held
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": null,
  "requestNumber": "string",
  "status": "prepared",
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "payoutAccountId": "string",
  "maskedAccount": "string",
  "currency": "string",
  "totalAmount": "string",
  "entryIds": [
    "string"
  ],
  "accountSnapshot": null,
  "exportBatchId": null,
  "exportedAt": null,
  "exportNote": null,
  "holdReasonCode": null,
  "holdNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/payout-requests/:id/hold" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"reasonCode\": \"manual_hold\",
  \"note\": null
}"
POST/api/freight/settlement/payout-requests/{id}/mark-exported
Auth requiredsettlement.export

Mark payout request exported

Requires features: settlement.export

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "exportBatchId": "string",
  "note": null
}

Responses

200Payout request exported
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runId": null,
  "requestNumber": "string",
  "status": "prepared",
  "carrierParticipantId": "string",
  "carrierOrganizationId": null,
  "payoutAccountId": "string",
  "maskedAccount": "string",
  "currency": "string",
  "totalAmount": "string",
  "entryIds": [
    "string"
  ],
  "accountSnapshot": null,
  "exportBatchId": null,
  "exportedAt": null,
  "exportNote": null,
  "holdReasonCode": null,
  "holdNote": null,
  "cancelledAt": null,
  "cancelNote": null,
  "revision": 1,
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/payout-requests/:id/mark-exported" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"exportBatchId\": \"string\",
  \"note\": null
}"
POST/api/freight/settlement/payout-requests/prepare
Auth requiredsettlement.manage

Prepare payout requests

Requires features: settlement.manage

Request body (application/json)

{
  "runId": null,
  "carrierParticipantId": null,
  "currency": null
}

Responses

200Payout requests prepared
Content-Type: application/json
{
  "payoutRequestIds": [
    "string"
  ],
  "preparedCount": 1
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/payout-requests/prepare" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"runId\": null,
  \"carrierParticipantId\": null,
  \"currency\": null
}"
GET/api/freight/settlement/runs
Auth requiredsettlement.view

List settlement runs

Requires features: settlement.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
searchqueryNoany
statusqueryNoany
triggerqueryNoany
sourceTypequeryNoany
sourceIdqueryNoany
fromqueryNoany
toqueryNoany
dryRunqueryNoany

Responses

200Settlement runs returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "runNumber": "string",
      "status": "queued",
      "trigger": "pod_event",
      "sourceType": null,
      "sourceId": null,
      "sourceKey": null,
      "parentRunId": null,
      "periodFrom": null,
      "periodTo": null,
      "dryRun": true,
      "progressJobId": null,
      "completedAt": null,
      "eligibleCount": 1,
      "heldCount": 1,
      "payoutPreparedCount": 1,
      "exportedCount": 1,
      "gateSummary": null,
      "failureDetails": null,
      "metadata": null,
      "requestedByUserId": null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}
400Invalid query
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/settlement/runs?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/settlement/runs
Auth requiredsettlement.manage

Create settlement run

Requires features: settlement.manage

Request body (application/json)

{
  "trigger": "manual",
  "sourceType": null,
  "sourceId": null,
  "periodFrom": null,
  "periodTo": null,
  "dryRun": false
}

Responses

202Settlement run queued
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runNumber": "string",
  "status": "queued",
  "trigger": "pod_event",
  "sourceType": null,
  "sourceId": null,
  "sourceKey": null,
  "parentRunId": null,
  "periodFrom": null,
  "periodTo": null,
  "dryRun": true,
  "progressJobId": null,
  "completedAt": null,
  "eligibleCount": 1,
  "heldCount": 1,
  "payoutPreparedCount": 1,
  "exportedCount": 1,
  "gateSummary": null,
  "failureDetails": null,
  "metadata": null,
  "requestedByUserId": null,
  "createdAt": "string",
  "updatedAt": "string"
}
400Invalid request
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/runs" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"trigger\": \"manual\",
  \"sourceType\": null,
  \"sourceId\": null,
  \"periodFrom\": null,
  \"periodTo\": null,
  \"dryRun\": false
}"
GET/api/freight/settlement/runs/{id}
Auth requiredsettlement.view

Get settlement run

Requires features: settlement.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Settlement run returned
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runNumber": "string",
  "status": "queued",
  "trigger": "pod_event",
  "sourceType": null,
  "sourceId": null,
  "sourceKey": null,
  "parentRunId": null,
  "periodFrom": null,
  "periodTo": null,
  "dryRun": true,
  "progressJobId": null,
  "completedAt": null,
  "eligibleCount": 1,
  "heldCount": 1,
  "payoutPreparedCount": 1,
  "exportedCount": 1,
  "gateSummary": null,
  "failureDetails": null,
  "metadata": null,
  "requestedByUserId": null,
  "createdAt": "string",
  "updatedAt": "string"
}
404Settlement run not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/settlement/runs/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/settlement/runs/{id}/cancel
Auth requiredsettlement.manage

Cancel settlement run

Requires features: settlement.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Settlement run cancelled
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runNumber": "string",
  "status": "queued",
  "trigger": "pod_event",
  "sourceType": null,
  "sourceId": null,
  "sourceKey": null,
  "parentRunId": null,
  "periodFrom": null,
  "periodTo": null,
  "dryRun": true,
  "progressJobId": null,
  "completedAt": null,
  "eligibleCount": 1,
  "heldCount": 1,
  "payoutPreparedCount": 1,
  "exportedCount": 1,
  "gateSummary": null,
  "failureDetails": null,
  "metadata": null,
  "requestedByUserId": null,
  "createdAt": "string",
  "updatedAt": "string"
}
400Invalid request
Content-Type: application/json
"string"
404Settlement run not found
Content-Type: application/json
"string"
409Settlement run is not cancellable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/runs/:id/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
GET/api/freight/settlement/runs/{id}/entries
Auth requiredsettlement.view

List settlement entries

Requires features: settlement.view

Parameters

NameInRequiredSchemaDescription
idpathYesany
pagequeryNoany
pageSizequeryNoany
cursorqueryNoany
idsqueryNoany
searchqueryNoany
runIdqueryNoany
payoutRequestIdqueryNoany
statusqueryNoany
carrierParticipantIdqueryNoany
marketplaceShipmentIdqueryNoany
sourceShipmentIdqueryNoany
gateCodequeryNoany
fromqueryNoany
toqueryNoany
currencyqueryNoany

Responses

200Settlement entries returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "runId": "string",
      "payoutRequestId": null,
      "entryNumber": "string",
      "status": "eligible",
      "sourceShipmentId": "string",
      "marketplaceShipmentId": "string",
      "sourceProposalId": "string",
      "marketplaceProposalId": "string",
      "sourcePricingEstimateId": null,
      "carrierParticipantId": "string",
      "carrierOrganizationId": null,
      "currency": "string",
      "grossAmount": "string",
      "netAmount": null,
      "taxAmount": null,
      "amountSource": "string",
      "gateFailures": null,
      "holdReasonCode": null,
      "holdNote": null,
      "releasedAt": null,
      "releaseNote": null,
      "cancelledAt": null,
      "cancelNote": null,
      "snapshot": null,
      "revision": 1,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/settlement/runs/:id/entries?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/settlement/runs/{id}/prepare-payouts
Auth requiredsettlement.manage

Prepare payout requests

Requires features: settlement.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "runId": null,
  "carrierParticipantId": null,
  "currency": null
}

Responses

200Payout requests prepared
Content-Type: application/json
{
  "payoutRequestIds": [
    "string"
  ],
  "preparedCount": 1
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/runs/:id/prepare-payouts" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"runId\": null,
  \"carrierParticipantId\": null,
  \"currency\": null
}"
POST/api/freight/settlement/runs/{id}/retry
Auth requiredsettlement.manage

Retry settlement run

Requires features: settlement.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "mode": "failed_only"
}

Responses

202Settlement retry run queued
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "runNumber": "string",
  "status": "queued",
  "trigger": "pod_event",
  "sourceType": null,
  "sourceId": null,
  "sourceKey": null,
  "parentRunId": null,
  "periodFrom": null,
  "periodTo": null,
  "dryRun": true,
  "progressJobId": null,
  "completedAt": null,
  "eligibleCount": 1,
  "heldCount": 1,
  "payoutPreparedCount": 1,
  "exportedCount": 1,
  "gateSummary": null,
  "failureDetails": null,
  "metadata": null,
  "requestedByUserId": null,
  "createdAt": "string",
  "updatedAt": "string"
}
400Invalid request
Content-Type: application/json
"string"
404Settlement run not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/settlement/runs/:id/retry" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"mode\": \"failed_only\"
}"

Freight Slots

Showing 4 of 4 endpoints
GET/api/freight/slots
Auth requiredslots.view

List freight slots

Requires features: slots.view

Responses

200Slot list returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "organizationId": "string",
      "locationId": "string",
      "location": null,
      "slotType": "LOADING",
      "startTime": null,
      "endTime": null,
      "cargoId": null,
      "cargo": null,
      "bookedByTenantId": null,
      "orderId": null,
      "status": "AVAILABLE",
      "modeData": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/slots" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/freight/slots/{id}
Auth requiredslots.view

Get slot detail

Requires features: slots.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Slot detail returned
Content-Type: application/json
{
  "id": "string",
  "tenantId": "string",
  "organizationId": "string",
  "locationId": "string",
  "location": null,
  "slotType": "LOADING",
  "startTime": null,
  "endTime": null,
  "cargoId": null,
  "cargo": null,
  "bookedByTenantId": null,
  "orderId": null,
  "status": "AVAILABLE",
  "modeData": null,
  "createdAt": null,
  "updatedAt": null
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/slots/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/freight/slots/{id}/cancel
Auth requiredslots.book

Cancel a freight slot

Requires features: slots.book

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Slot cancelled
Content-Type: application/json
{
  "id": "string",
  "status": "CANCELLED"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/freight/slots/:id/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/slots/book
Auth requiredslots.book

Book a freight slot

Requires features: slots.book

Request body (application/json)

{
  "locationId": "string",
  "slotType": "LOADING",
  "startTime": "string",
  "endTime": "string",
  "cargoId": null
}

Responses

201Slot booked
Content-Type: application/json
{
  "id": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/slots/book" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"locationId\": \"string\",
  \"slotType\": \"LOADING\",
  \"startTime\": \"string\",
  \"endTime\": \"string\",
  \"cargoId\": null
}"

Freight Suggestions

Showing 7 of 7 endpoints
GET/api/freight/suggestions
Auth requiredsuggestions.view

List automation suggestions

Requires features: suggestions.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
idsqueryNoany
searchqueryNoany
sourceTypequeryNoany
sourceIdqueryNoany
statusqueryNoany
recommendationqueryNoany
isCurrentqueryNoany

Responses

200Automation suggestions returned
Content-Type: application/json
{
  "items": [
    {
      "id": "string",
      "sourceType": "marketplace_shipment",
      "sourceId": "string",
      "sourceLabel": null,
      "status": "draft",
      "kind": "carrier",
      "recommendation": "recommended",
      "confidenceScore": null,
      "optimizationRunId": null,
      "optimizationCandidateId": null,
      "matchRunId": null,
      "matchCandidateId": null,
      "routingRouteId": null,
      "routingMatrixRunId": null,
      "proposedCarrierParticipantId": null,
      "proposedCarrierOrganizationId": null,
      "proposedPickupAt": null,
      "proposedDeliveryAt": null,
      "actionDraftType": "proposal_draft",
      "summary": null,
      "failureCode": null,
      "isCurrent": true,
      "sensitiveEvidenceAvailable": true,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1,
  "totalPages": 1
}
400Invalid query
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/suggestions?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/suggestions
Auth requiredsuggestions.generate

Generate automation suggestion

Requires features: suggestions.generate

Request body (application/json)

{
  "sourceType": "marketplace_shipment",
  "sourceId": "string",
  "objective": "balanced",
  "forceRefresh": false,
  "allowFallback": true,
  "candidateLimit": 20
}

Responses

201Automation suggestion generated
Content-Type: application/json
{
  "id": "string",
  "sourceType": "marketplace_shipment",
  "sourceId": "string",
  "sourceLabel": null,
  "status": "draft",
  "kind": "carrier",
  "recommendation": "recommended",
  "confidenceScore": null,
  "optimizationRunId": null,
  "optimizationCandidateId": null,
  "matchRunId": null,
  "matchCandidateId": null,
  "routingRouteId": null,
  "routingMatrixRunId": null,
  "proposedCarrierParticipantId": null,
  "proposedCarrierOrganizationId": null,
  "proposedPickupAt": null,
  "proposedDeliveryAt": null,
  "actionDraftType": "proposal_draft",
  "summary": null,
  "failureCode": null,
  "isCurrent": true,
  "sensitiveEvidenceAvailable": true,
  "createdAt": "string",
  "updatedAt": "string",
  "decisions": [
    {
      "id": "string",
      "suggestionId": "string",
      "decisionType": "accept",
      "previousStatus": "draft",
      "nextStatus": "draft",
      "actorUserId": null,
      "note": null,
      "actionDraft": null,
      "createdAt": "string"
    }
  ],
  "actionDraft": null
}
400Invalid request
Content-Type: application/json
"string"
404Source not found
Content-Type: application/json
"string"
424Evidence unavailable
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/suggestions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"sourceType\": \"marketplace_shipment\",
  \"sourceId\": \"string\",
  \"objective\": \"balanced\",
  \"forceRefresh\": false,
  \"allowFallback\": true,
  \"candidateLimit\": 20
}"
GET/api/freight/suggestions/{id}
Auth requiredsuggestions.view

Get automation suggestion

Requires features: suggestions.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Automation suggestion returned
Content-Type: application/json
{
  "id": "string",
  "sourceType": "marketplace_shipment",
  "sourceId": "string",
  "sourceLabel": null,
  "status": "draft",
  "kind": "carrier",
  "recommendation": "recommended",
  "confidenceScore": null,
  "optimizationRunId": null,
  "optimizationCandidateId": null,
  "matchRunId": null,
  "matchCandidateId": null,
  "routingRouteId": null,
  "routingMatrixRunId": null,
  "proposedCarrierParticipantId": null,
  "proposedCarrierOrganizationId": null,
  "proposedPickupAt": null,
  "proposedDeliveryAt": null,
  "actionDraftType": "proposal_draft",
  "summary": null,
  "failureCode": null,
  "isCurrent": true,
  "sensitiveEvidenceAvailable": true,
  "createdAt": "string",
  "updatedAt": "string",
  "decisions": [
    {
      "id": "string",
      "suggestionId": "string",
      "decisionType": "accept",
      "previousStatus": "draft",
      "nextStatus": "draft",
      "actorUserId": null,
      "note": null,
      "actionDraft": null,
      "createdAt": "string"
    }
  ],
  "actionDraft": null
}
404Suggestion not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/freight/suggestions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/suggestions/{id}/accept
Auth requiredsuggestions.decide

Accept automation suggestion

Requires features: suggestions.decide

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Suggestion accepted
Content-Type: application/json
{
  "id": "string",
  "suggestionId": "string",
  "decisionType": "accept",
  "status": "draft",
  "actionDraft": null
}
404Suggestion not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/suggestions/:id/accept" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
POST/api/freight/suggestions/{id}/override
Auth requiredsuggestions.decide

Override automation suggestion

Requires features: suggestions.decide

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "actionDraft": {
    "type": "proposal_draft",
    "payload": {
      "carrierParticipantId": "string",
      "carrierOrganizationId": "string",
      "pricingEstimateId": null,
      "currency": null,
      "totalAmount": null,
      "expiresAt": null,
      "description": null,
      "termsText": null,
      "metadataJson": null
    }
  },
  "note": null
}

Responses

200Suggestion overridden
Content-Type: application/json
{
  "id": "string",
  "suggestionId": "string",
  "decisionType": "accept",
  "status": "draft",
  "actionDraft": null
}
404Suggestion not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/suggestions/:id/override" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"actionDraft\": {
    \"type\": \"proposal_draft\",
    \"payload\": {
      \"carrierParticipantId\": \"string\",
      \"carrierOrganizationId\": \"string\",
      \"pricingEstimateId\": null,
      \"currency\": null,
      \"totalAmount\": null,
      \"expiresAt\": null,
      \"description\": null,
      \"termsText\": null,
      \"metadataJson\": null
    }
  },
  \"note\": null
}"
POST/api/freight/suggestions/{id}/reject
Auth requiredsuggestions.decide

Reject automation suggestion

Requires features: suggestions.decide

Parameters

NameInRequiredSchemaDescription
idpathYesany

Request body (application/json)

{
  "note": null
}

Responses

200Suggestion rejected
Content-Type: application/json
{
  "id": "string",
  "suggestionId": "string",
  "decisionType": "accept",
  "status": "draft",
  "actionDraft": null
}
404Suggestion not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/freight/suggestions/:id/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"note\": null
}"
GET/api/freight/suggestions/shipments/{id}/summary
Auth requiredsuggestions.view

Get current shipment automation suggestion

Requires features: suggestions.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Current suggestion returned
Content-Type: application/json
{
  "suggestion": null
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/suggestions/shipments/:id/summary" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Freight Tracking

Showing 3 of 3 endpoints
GET/api/freight/tracking/events
Auth requiredtracking.view

List tracking timeline events.

Requires features: tracking.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
eventTypequeryNoany
subjectTypequeryNoany
subjectIdqueryNoany
transportContextKindqueryNoany
transportContextIdqueryNoany
cargoIdqueryNoany
modequeryNoany
sourcequeryNoany

Responses

200Paginated tracking timeline events.
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "eventType": "string",
      "happenedAt": "string",
      "subjectType": "string",
      "subjectId": "string",
      "subjectLabel": null,
      "source": "string",
      "sourceEventId": null,
      "mode": null,
      "transportContextKind": null,
      "transportContextId": null,
      "cargoId": null,
      "payload": {},
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/tracking/events?page=1&pageSize=50" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/freight/tracking/events
Auth requiredtracking.record

Record a tracking timeline event.

Requires features: tracking.record

Request body (application/json)

{
  "eventType": "string",
  "subjectType": "string",
  "subjectId": "string",
  "subjectLabel": null,
  "source": "string",
  "sourceEventId": null,
  "mode": null,
  "transportContextKind": null,
  "transportContextId": null,
  "cargoId": null,
  "payload": {}
}

Responses

201Tracking event created.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "eventType": "string",
  "happenedAt": "string",
  "subjectType": "string",
  "subjectId": "string",
  "subjectLabel": null,
  "source": "string",
  "sourceEventId": null,
  "mode": null,
  "transportContextKind": null,
  "transportContextId": null,
  "cargoId": null,
  "payload": {},
  "createdAt": "string",
  "updatedAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/freight/tracking/events" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"eventType\": \"string\",
  \"subjectType\": \"string\",
  \"subjectId\": \"string\",
  \"subjectLabel\": null,
  \"source\": \"string\",
  \"sourceEventId\": null,
  \"mode\": null,
  \"transportContextKind\": null,
  \"transportContextId\": null,
  \"cargoId\": null,
  \"payload\": {}
}"
GET/api/freight/tracking/events/{id}
Auth requiredtracking.view

Get a tracking event.

Requires features: tracking.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Tracking event detail.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "eventType": "string",
  "happenedAt": "string",
  "subjectType": "string",
  "subjectId": "string",
  "subjectLabel": null,
  "source": "string",
  "sourceEventId": null,
  "mode": null,
  "transportContextKind": null,
  "transportContextId": null,
  "cargoId": null,
  "payload": {},
  "createdAt": "string",
  "updatedAt": "string"
}
404Tracking event not found.
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/freight/tracking/events/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

InboxOps

Showing 19 of 19 endpoints
GET/api/inbox_ops/emails
Auth requiredinbox_ops.log.view

List received emails

Processing log of all received emails Requires features: inbox_ops.log.view

Responses

200Paginated list of emails
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/inbox_ops/emails" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/inbox_ops/emails/{id}
Auth requiredinbox_ops.log.view

Get email detail with parsed thread

Requires features: inbox_ops.log.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Email detail
Content-Type: application/json
"string"
404Email not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/inbox_ops/emails/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/inbox_ops/emails/{id}
Auth requiredinbox_ops.proposals.manage

Soft-delete an inbox email

Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Email deleted
Content-Type: application/json
"string"
404Email not found
Content-Type: application/json
"string"

Example

curl -X DELETE "https://api.open-mercato.local/api/inbox_ops/emails/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/emails/{id}/reprocess
Auth requiredinbox_ops.proposals.manage

Re-trigger LLM extraction on a failed or low-confidence email

Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Email queued for reprocessing
Content-Type: application/json
"string"
404Email not found
Content-Type: application/json
"string"
409Email is already processing or proposal cannot be superseded safely
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/emails/:id/reprocess" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/extract
Auth requiredinbox_ops.proposals.manage

Submit raw text for LLM extraction

Creates an InboxEmail record from raw text and triggers the extraction pipeline. The extraction runs asynchronously. Requires features: inbox_ops.proposals.manage

Responses

200Extraction queued successfully
Content-Type: application/json
"string"
400Invalid request body
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/extract" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/inbox_ops/proposals
Auth requiredinbox_ops.proposals.view

List proposals

List inbox proposals with optional status filter and pagination Requires features: inbox_ops.proposals.view

Responses

200Paginated list of proposals
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/inbox_ops/proposals" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/inbox_ops/proposals/{id}
Auth requiredinbox_ops.proposals.view

Get proposal detail

Returns proposal with actions, discrepancies, and source email Requires features: inbox_ops.proposals.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Full proposal detail
Content-Type: application/json
"string"
404Proposal not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/inbox_ops/proposals/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/proposals/{id}/accept-all
Auth requiredinbox_ops.proposals.manage

Accept and execute all pending actions in a proposal

Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200All actions processed
Content-Type: application/json
"string"
404Proposal not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/proposals/:id/accept-all" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/inbox_ops/proposals/{id}/actions/{actionId}
Auth requiredinbox_ops.proposals.manage

Edit action payload before accepting

Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany
actionIdpathYesany

Responses

200Action updated
Content-Type: application/json
"string"
404Action not found
Content-Type: application/json
"string"
409Action already processed
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/inbox_ops/proposals/:id/actions/:actionId" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/proposals/{id}/actions/{actionId}/accept
Auth requiredinbox_ops.proposals.manage

Accept and execute a proposal action

Executes the action and creates the entity in the target module. Returns 409 if already processed. Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany
actionIdpathYesany

Responses

200Action executed successfully
Content-Type: application/json
"string"
404Action not found
Content-Type: application/json
"string"
409Action already processed
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/proposals/:id/actions/:actionId/accept" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/inbox_ops/proposals/{id}/actions/{actionId}/complete
Auth requiredinbox_ops.proposals.manage

Mark an action as completed with an externally-created entity

Used when an action is fulfilled through the normal sales form instead of the execution engine. Updates the action status without running the execution engine. Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany
actionIdpathYesany

Responses

200Action marked as completed
Content-Type: application/json
"string"
400Invalid body
Content-Type: application/json
"string"
404Action not found
Content-Type: application/json
"string"
409Action already processed
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/inbox_ops/proposals/:id/actions/:actionId/complete" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/proposals/{id}/actions/{actionId}/reject
Auth requiredinbox_ops.proposals.manage

Reject a proposal action

Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany
actionIdpathYesany

Responses

200Action rejected
Content-Type: application/json
"string"
404Action not found
Content-Type: application/json
"string"
409Action already processed
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/proposals/:id/actions/:actionId/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/proposals/{id}/categorize
Auth requiredinbox_ops.proposals.manage

Set or change the category of a proposal

Assigns a category to a proposal. Returns the new and previous category for undo support. Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Category updated
Content-Type: application/json
"string"
400Invalid category value
Content-Type: application/json
"string"
404Proposal not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/proposals/:id/categorize" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/proposals/{id}/reject
Auth requiredinbox_ops.proposals.manage

Reject entire proposal (all pending actions)

Requires features: inbox_ops.proposals.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Proposal rejected
Content-Type: application/json
"string"
404Proposal not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/proposals/:id/reject" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/proposals/{id}/replies/{replyId}/send
Auth requiredinbox_ops.replies.send

Send a draft reply email and register it in messages when available

Sends the draft_reply action payload via the configured email provider. When the messages module is available, also records the sent reply as an internal message record. Sets In-Reply-To and References headers for threading. Requires features: inbox_ops.replies.send

Parameters

NameInRequiredSchemaDescription
idpathYesany
replyIdpathYesany

Responses

200Reply sent successfully
Content-Type: application/json
"string"
400Missing required payload fields
Content-Type: application/json
"string"
404Reply action not found
Content-Type: application/json
"string"
409Action in invalid state for sending
Content-Type: application/json
"string"
502Email delivery failed
Content-Type: application/json
"string"
503Email service not configured or disabled
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/proposals/:id/replies/:replyId/send" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/inbox_ops/proposals/{id}/translate
Auth requiredinbox_ops.proposals.view

Translate proposal content

Translates the proposal summary and action descriptions to the target locale. Results are cached. Requires features: inbox_ops.proposals.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Translation result
Content-Type: application/json
"string"
400Invalid target locale or same language
Content-Type: application/json
"string"
404Proposal not found
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/inbox_ops/proposals/:id/translate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/inbox_ops/proposals/counts
Auth requiredinbox_ops.proposals.view

Get proposal status and category counts

Returns counts by status and by category for tab badges and filter dropdowns Requires features: inbox_ops.proposals.view

Responses

200Status and category counts object
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/inbox_ops/proposals/counts" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/inbox_ops/settings
Auth requiredinbox_ops.settings.manage

Get tenant inbox configuration

Returns the forwarding address and configuration for this tenant Requires features: inbox_ops.settings.manage

Responses

200Inbox settings
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/inbox_ops/settings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/inbox_ops/settings
Auth requiredinbox_ops.settings.manage

Update tenant inbox configuration

Updates working language and/or active status Requires features: inbox_ops.settings.manage

Responses

200Updated settings
Content-Type: application/json
"string"
404Settings not found
Content-Type: application/json
"string"

Example

curl -X PATCH "https://api.open-mercato.local/api/inbox_ops/settings" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Demo

Showing 1 of 1 endpoints
POST/api/onboarding/demo-feedback

Submit demo feedback

Sends a feedback/contact request from the demo environment to the admin and optionally to the user.

Request body (application/json)

{
  "email": "[email protected]",
  "message": "",
  "termsAccepted": true,
  "marketingConsent": false,
  "sendCopy": true
}

Responses

200Feedback sent successfully.
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/onboarding/demo-feedback" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
  \"email\": \"[email protected]\",
  \"message\": \"\",
  \"termsAccepted\": true,
  \"marketingConsent\": false,
  \"sendCopy\": true
}"

PaymentGateways

Showing 10 of 10 endpoints
POST/api/payment_gateways/cancel
Auth requiredpayment_gateways.manage

Cancel payment

Requires features: payment_gateways.manage

Responses

200Payment cancelled
Content-Type: application/json
"string"
422Invalid payload
Content-Type: application/json
"string"
502Gateway provider error
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/payment_gateways/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/payment_gateways/capture
Auth requiredpayment_gateways.capture

Capture payment

Requires features: payment_gateways.capture

Responses

200Payment captured
Content-Type: application/json
"string"
422Invalid payload
Content-Type: application/json
"string"
502Gateway provider error
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/payment_gateways/capture" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/payment_gateways/providers
Auth requiredpayment_gateways.view

List payment gateway descriptors

Requires features: payment_gateways.view

Responses

200List of safe payment gateway descriptors
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/payment_gateways/providers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/payment_gateways/providers/{providerKey}
Auth requiredpayment_gateways.view

Get payment gateway descriptor

Requires features: payment_gateways.view

Parameters

NameInRequiredSchemaDescription
providerKeypathYesany

Responses

200Provider descriptor
Content-Type: application/json
"string"
404Provider descriptor not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/payment_gateways/providers/:providerKey" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/payment_gateways/refund
Auth requiredpayment_gateways.refund

Refund payment

Requires features: payment_gateways.refund

Responses

200Payment refunded
Content-Type: application/json
"string"
422Invalid payload
Content-Type: application/json
"string"
502Gateway provider error
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/payment_gateways/refund" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/payment_gateways/sessions
Auth requiredpayment_gateways.manage

Create payment session

Requires features: payment_gateways.manage

Responses

201Payment session created
Content-Type: application/json
"string"
422Invalid payload or unknown provider
Content-Type: application/json
"string"
502Gateway provider error
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/payment_gateways/sessions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/payment_gateways/status
Auth requiredpayment_gateways.view

Get transaction status

Requires features: payment_gateways.view

Responses

200Transaction status
Content-Type: application/json
"string"
404Transaction not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/payment_gateways/status" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/payment_gateways/transactions
Auth requiredpayment_gateways.view

List payment transactions

Requires features: payment_gateways.view

Responses

200Payment transaction list
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/payment_gateways/transactions" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/payment_gateways/transactions/{id}
Auth requiredpayment_gateways.view

Get payment transaction details

Requires features: payment_gateways.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Payment transaction details
Content-Type: application/json
"string"
404Transaction not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/payment_gateways/transactions/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/payment_gateways/webhook/{provider}

Process inbound webhook from payment provider

Parameters

NameInRequiredSchemaDescription
providerpathYesany

Responses

202Webhook accepted for async processing
Content-Type: application/json
"string"
401Signature verification failed
Content-Type: application/json
"string"
404Unknown provider
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/payment_gateways/webhook/:provider" \
  -H "Accept: application/json"

APHEX Project Hub

Showing 20 of 20 endpoints
PATCH/api/project-hub/acceptance-issues/{id}
Auth requiredaphex_project_hubs.manage

Triage APHEX project module acceptance issue

Requires features: aphex_project_hubs.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/project-hub/acceptance-issues/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/project-hub/acceptance-requests/{id}
Auth requiredaphex_project_hubs.acceptance.manage

Cancel or supersede APHEX project module acceptance

Requires features: aphex_project_hubs.acceptance.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/project-hub/acceptance-requests/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/project-hub/modules
Auth requiredaphex_project_hubs.view

List or create APHEX project modules

Requires features: aphex_project_hubs.view

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/project-hub/modules" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/project-hub/modules
Auth requiredaphex_project_hubs.manage

List or create APHEX project modules

Requires features: aphex_project_hubs.manage

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/project-hub/modules" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/project-hub/modules/{id}
Auth requiredaphex_project_hubs.view

Read or update an APHEX project module

Requires features: aphex_project_hubs.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/project-hub/modules/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/project-hub/modules/{id}
Auth requiredaphex_project_hubs.manage

Read or update an APHEX project module

Requires features: aphex_project_hubs.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/project-hub/modules/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/project-hub/modules/{id}
Auth requiredaphex_project_hubs.manage

Read or update an APHEX project module

Requires features: aphex_project_hubs.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/project-hub/modules/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/project-hub/modules/{id}/acceptance-requests
Auth requiredaphex_project_hubs.acceptance.manage

Request APHEX project module acceptance

Requires features: aphex_project_hubs.acceptance.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/project-hub/modules/:id/acceptance-requests" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/project-hub/modules/{id}/checks
Auth requiredaphex_project_hubs.verify

Update APHEX project module checks

Requires features: aphex_project_hubs.verify

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/project-hub/modules/:id/checks" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/project-hub/modules/{id}/evidence
Auth requiredaphex_project_hubs.view

List or add APHEX project evidence

Requires features: aphex_project_hubs.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/project-hub/modules/:id/evidence" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/project-hub/modules/{id}/evidence
Auth requiredaphex_project_hubs.manage

List or add APHEX project evidence

Requires features: aphex_project_hubs.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/project-hub/modules/:id/evidence" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
PATCH/api/project-hub/modules/{id}/evidence/{evidenceId}
Auth requiredaphex_project_hubs.manage

Update or delete APHEX project evidence

Requires features: aphex_project_hubs.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany
evidenceIdpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/project-hub/modules/:id/evidence/:evidenceId" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
DELETE/api/project-hub/modules/{id}/evidence/{evidenceId}
Auth requiredaphex_project_hubs.manage

Update or delete APHEX project evidence

Requires features: aphex_project_hubs.manage

Parameters

NameInRequiredSchemaDescription
idpathYesany
evidenceIdpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X DELETE "https://api.open-mercato.local/api/project-hub/modules/:id/evidence/:evidenceId" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/project-hub/modules/bulk
Auth requiredaphex_project_hubs.manage

Bulk import APHEX project modules

Requires features: aphex_project_hubs.manage

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/project-hub/modules/bulk" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/project-hub/portal/acceptance-requests

List assigned APHEX acceptance requests

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/project-hub/portal/acceptance-requests" \
  -H "Accept: application/json"
POST/api/project-hub/portal/acceptance-requests/{id}/decision

Submit APHEX project module acceptance decision

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/project-hub/portal/acceptance-requests/:id/decision" \
  -H "Accept: application/json"
POST/api/project-hub/portal/acceptance-requests/{id}/issues

Create APHEX project acceptance feedback

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/project-hub/portal/acceptance-requests/:id/issues" \
  -H "Accept: application/json"
PATCH/api/project-hub/portal/acceptance-requests/{id}/issues/{issueId}

Update own APHEX project acceptance feedback

Parameters

NameInRequiredSchemaDescription
idpathYesany
issueIdpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X PATCH "https://api.open-mercato.local/api/project-hub/portal/acceptance-requests/:id/issues/:issueId" \
  -H "Accept: application/json"
GET/api/project-hub/portal/modules

List collaborator-safe APHEX project modules

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/project-hub/portal/modules" \
  -H "Accept: application/json"
GET/api/project-hub/portal/modules/{id}

Read collaborator-safe APHEX project module detail

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200OK
Content-Type: application/json
{}
400Validation failed
Content-Type: application/json
{
  "error": "string"
}
401Unauthorized
Content-Type: application/json
{
  "error": "string"
}
403Forbidden
Content-Type: application/json
{
  "error": "string"
}
404Not found
Content-Type: application/json
{
  "error": "string"
}
409Conflict
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/project-hub/portal/modules/:id" \
  -H "Accept: application/json"

RateLimitProbe

Showing 1 of 1 endpoints
POST/api/ratelimit_probe/ping

Test-only endpoint with per-route metadata.rateLimit — used to prove rate-limit leakage under OM_INTEGRATION_TEST

Responses

200Always OK when under the points budget
Content-Type: application/json
{
  "ok": true
}
429Rate limit exceeded (3 points / 60 s per client IP)
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/ratelimit_probe/ping" \
  -H "Accept: application/json"

Road Routing

Showing 14 of 14 endpoints
GET/api/road/geofences
Auth requiredrouting.view

Lists geofences.

Requires features: routing.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
idsqueryNoany
searchqueryNoany
locationIdqueryNoany
typequeryNoany
isActivequeryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Geofences returned
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "type": "TERMINAL",
      "centerLat": 1,
      "centerLng": 1,
      "radiusKm": 1,
      "polygon": null,
      "locationId": null,
      "linkedEntityType": null,
      "linkedEntityId": null,
      "triggerOnEnter": true,
      "triggerOnExit": true,
      "notificationTargets": null,
      "isActive": true,
      "metadata": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/road/geofences?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/geofences
Auth requiredrouting.manage

Creates a geofence.

Requires features: routing.manage

Request body (application/json)

{
  "name": "string",
  "type": "TERMINAL",
  "centerLat": 1,
  "centerLng": 1,
  "radiusKm": 1,
  "polygon": null,
  "locationId": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "triggerOnEnter": true,
  "triggerOnExit": false,
  "notificationTargets": null,
  "isActive": true,
  "metadata": null
}

Responses

201Geofence created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "type": "TERMINAL",
  "centerLat": 1,
  "centerLng": 1,
  "radiusKm": 1,
  "polygon": null,
  "locationId": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "triggerOnEnter": true,
  "triggerOnExit": true,
  "notificationTargets": null,
  "isActive": true,
  "metadata": null,
  "createdAt": null,
  "updatedAt": null
}

Example

curl -X POST "https://api.open-mercato.local/api/road/geofences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"type\": \"TERMINAL\",
  \"centerLat\": 1,
  \"centerLng\": 1,
  \"radiusKm\": 1,
  \"polygon\": null,
  \"locationId\": null,
  \"linkedEntityType\": null,
  \"linkedEntityId\": null,
  \"triggerOnEnter\": true,
  \"triggerOnExit\": false,
  \"notificationTargets\": null,
  \"isActive\": true,
  \"metadata\": null
}"
PUT/api/road/geofences
Auth requiredrouting.manage

Updates a geofence.

Requires features: routing.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "polygon": null,
  "locationId": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "notificationTargets": null,
  "metadata": null
}

Responses

200Geofence updated
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "type": "TERMINAL",
  "centerLat": 1,
  "centerLng": 1,
  "radiusKm": 1,
  "polygon": null,
  "locationId": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "triggerOnEnter": true,
  "triggerOnExit": true,
  "notificationTargets": null,
  "isActive": true,
  "metadata": null,
  "createdAt": null,
  "updatedAt": null
}

Example

curl -X PUT "https://api.open-mercato.local/api/road/geofences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"polygon\": null,
  \"locationId\": null,
  \"linkedEntityType\": null,
  \"linkedEntityId\": null,
  \"notificationTargets\": null,
  \"metadata\": null
}"
DELETE/api/road/geofences
Auth requiredrouting.manage

Deletes a geofence.

Requires features: routing.manage

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000"
}

Responses

200Geofence deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/road/geofences" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\"
}"
GET/api/road/geofences/{id}
Auth requiredrouting.view

Returns a single geofence.

Requires features: routing.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Geofence returned
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "type": "TERMINAL",
  "centerLat": 1,
  "centerLng": 1,
  "radiusKm": 1,
  "polygon": null,
  "locationId": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "triggerOnEnter": true,
  "triggerOnExit": true,
  "notificationTargets": null,
  "isActive": true,
  "metadata": null,
  "createdAt": null,
  "updatedAt": null
}
404Geofence not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/road/geofences/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/road/routes
Auth requiredrouting.view

Lists immutable road route snapshots.

Requires features: routing.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
idsqueryNoany
dispatchIdqueryNoany
legIdqueryNoany
providerqueryNoany
sourcequeryNoany
confidencequeryNoany
linkedEntityTypequeryNoany
linkedEntityIdqueryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Routes returned
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "tenantId": "00000000-0000-4000-8000-000000000000",
      "organizationId": "00000000-0000-4000-8000-000000000000",
      "legId": null,
      "dispatchId": null,
      "origin": {
        "lat": 1,
        "lng": 1,
        "label": null,
        "address": null
      },
      "destination": {
        "lat": 1,
        "lng": 1,
        "label": null,
        "address": null
      },
      "waypoints": null,
      "distanceKm": 1,
      "durationMinutes": 1,
      "trafficDelayMinutes": null,
      "polyline": "string",
      "boundingBox": null,
      "countrySegments": [
        {
          "country": "string",
          "distanceKm": 1,
          "durationMinutes": 1
        }
      ],
      "tollSegments": null,
      "totalCostPln": null,
      "costBreakdown": null,
      "fuelEstimateLiters": null,
      "transportMode": "string",
      "vehicleProfile": null,
      "provider": "HERE",
      "providerRequestId": null,
      "source": "live",
      "confidence": "high",
      "degradedReasonCode": null,
      "cacheKey": null,
      "cacheAgeSeconds": null,
      "linkedEntityType": null,
      "linkedEntityId": null,
      "calculatedAt": "string",
      "createdAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/road/routes?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/routes
Auth requiredrouting.manage

Creates an immutable road route snapshot.

Requires features: routing.manage

Request body (application/json)

{
  "legId": null,
  "dispatchId": null,
  "origin": {
    "lat": 1,
    "lng": 1,
    "label": null,
    "address": null
  },
  "destination": {
    "lat": 1,
    "lng": 1,
    "label": null,
    "address": null
  },
  "waypoints": null,
  "distanceKm": 1,
  "durationMinutes": 1,
  "trafficDelayMinutes": null,
  "polyline": "string",
  "boundingBox": null,
  "countrySegments": [
    {
      "country": "string",
      "distanceKm": 1,
      "durationMinutes": 1
    }
  ],
  "tollSegments": null,
  "totalCostPln": null,
  "costBreakdown": null,
  "fuelEstimateLiters": null,
  "transportMode": "TRUCK",
  "vehicleProfile": null,
  "provider": "HERE",
  "providerRequestId": null,
  "source": "live",
  "confidence": "medium",
  "degradedReasonCode": null,
  "cacheKey": null,
  "cacheAgeSeconds": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "providerPayload": null
}

Responses

201Route created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "legId": null,
  "dispatchId": null,
  "origin": {
    "lat": 1,
    "lng": 1,
    "label": null,
    "address": null
  },
  "destination": {
    "lat": 1,
    "lng": 1,
    "label": null,
    "address": null
  },
  "waypoints": null,
  "distanceKm": 1,
  "durationMinutes": 1,
  "trafficDelayMinutes": null,
  "polyline": "string",
  "boundingBox": null,
  "countrySegments": [
    {
      "country": "string",
      "distanceKm": 1,
      "durationMinutes": 1
    }
  ],
  "tollSegments": null,
  "totalCostPln": null,
  "costBreakdown": null,
  "fuelEstimateLiters": null,
  "transportMode": "string",
  "vehicleProfile": null,
  "provider": "HERE",
  "providerRequestId": null,
  "source": "live",
  "confidence": "high",
  "degradedReasonCode": null,
  "cacheKey": null,
  "cacheAgeSeconds": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "calculatedAt": "string",
  "createdAt": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/road/routes" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"legId\": null,
  \"dispatchId\": null,
  \"origin\": {
    \"lat\": 1,
    \"lng\": 1,
    \"label\": null,
    \"address\": null
  },
  \"destination\": {
    \"lat\": 1,
    \"lng\": 1,
    \"label\": null,
    \"address\": null
  },
  \"waypoints\": null,
  \"distanceKm\": 1,
  \"durationMinutes\": 1,
  \"trafficDelayMinutes\": null,
  \"polyline\": \"string\",
  \"boundingBox\": null,
  \"countrySegments\": [
    {
      \"country\": \"string\",
      \"distanceKm\": 1,
      \"durationMinutes\": 1
    }
  ],
  \"tollSegments\": null,
  \"totalCostPln\": null,
  \"costBreakdown\": null,
  \"fuelEstimateLiters\": null,
  \"transportMode\": \"TRUCK\",
  \"vehicleProfile\": null,
  \"provider\": \"HERE\",
  \"providerRequestId\": null,
  \"source\": \"live\",
  \"confidence\": \"medium\",
  \"degradedReasonCode\": null,
  \"cacheKey\": null,
  \"cacheAgeSeconds\": null,
  \"linkedEntityType\": null,
  \"linkedEntityId\": null,
  \"providerPayload\": null
}"
GET/api/road/routes/{id}
Auth requiredrouting.view

Returns a single immutable road route snapshot.

Requires features: routing.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Route returned
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000",
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "legId": null,
  "dispatchId": null,
  "origin": {
    "lat": 1,
    "lng": 1,
    "label": null,
    "address": null
  },
  "destination": {
    "lat": 1,
    "lng": 1,
    "label": null,
    "address": null
  },
  "waypoints": null,
  "distanceKm": 1,
  "durationMinutes": 1,
  "trafficDelayMinutes": null,
  "polyline": "string",
  "boundingBox": null,
  "countrySegments": [
    {
      "country": "string",
      "distanceKm": 1,
      "durationMinutes": 1
    }
  ],
  "tollSegments": null,
  "totalCostPln": null,
  "costBreakdown": null,
  "fuelEstimateLiters": null,
  "transportMode": "string",
  "vehicleProfile": null,
  "provider": "HERE",
  "providerRequestId": null,
  "source": "live",
  "confidence": "high",
  "degradedReasonCode": null,
  "cacheKey": null,
  "cacheAgeSeconds": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "calculatedAt": "string",
  "createdAt": "string"
}
404Route not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/road/routes/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/routing/calculate
Auth requiredrouting.manage

Calculates a route from coordinates or a linked shipment/dispatch entity.

Requires features: routing.manage

Request body (application/json)

{
  "waypoints": [],
  "dispatchId": null,
  "legId": null,
  "mode": "road",
  "transportMode": "TRUCK",
  "vehicleProfile": null,
  "departureAt": null,
  "maxAgeSeconds": null,
  "forceRefresh": false
}

Responses

201Route calculated
Content-Type: application/json
{
  "route": {
    "id": "00000000-0000-4000-8000-000000000000",
    "legId": null,
    "dispatchId": null,
    "linkedEntityType": null,
    "linkedEntityId": null,
    "originLabel": null,
    "destinationLabel": null,
    "origin": {
      "lat": 1,
      "lng": 1,
      "label": null,
      "address": null
    },
    "destination": {
      "lat": 1,
      "lng": 1,
      "label": null,
      "address": null
    },
    "distanceKm": 1,
    "durationMinutes": 1,
    "trafficDelayMinutes": null,
    "polyline": null,
    "provider": "HERE",
    "source": "live",
    "confidence": "high",
    "degradedReasonCode": null,
    "cacheAgeSeconds": null,
    "calculatedAt": "string"
  },
  "meta": {
    "cacheHit": true,
    "fallbackUsed": true,
    "providerHealth": "healthy"
  }
}
422Route points are incomplete
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/road/routing/calculate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"waypoints\": [],
  \"dispatchId\": null,
  \"legId\": null,
  \"mode\": \"road\",
  \"transportMode\": \"TRUCK\",
  \"vehicleProfile\": null,
  \"departureAt\": null,
  \"maxAgeSeconds\": null,
  \"forceRefresh\": false
}"
POST/api/road/routing/eta
Auth requiredrouting.manage

Refreshes ETA by recalculating the current route contract.

Requires features: routing.manage

Request body (application/json)

{
  "waypoints": [],
  "dispatchId": null,
  "legId": null,
  "mode": "road",
  "transportMode": "TRUCK",
  "vehicleProfile": null,
  "departureAt": null,
  "maxAgeSeconds": null,
  "forceRefresh": false,
  "routeId": null
}

Responses

201ETA refreshed
Content-Type: application/json
{
  "route": {
    "id": "00000000-0000-4000-8000-000000000000",
    "legId": null,
    "dispatchId": null,
    "linkedEntityType": null,
    "linkedEntityId": null,
    "originLabel": null,
    "destinationLabel": null,
    "origin": {
      "lat": 1,
      "lng": 1,
      "label": null,
      "address": null
    },
    "destination": {
      "lat": 1,
      "lng": 1,
      "label": null,
      "address": null
    },
    "distanceKm": 1,
    "durationMinutes": 1,
    "trafficDelayMinutes": null,
    "polyline": null,
    "provider": "HERE",
    "source": "live",
    "confidence": "high",
    "degradedReasonCode": null,
    "cacheAgeSeconds": null,
    "calculatedAt": "string"
  },
  "meta": {
    "cacheHit": true,
    "fallbackUsed": true,
    "providerHealth": "healthy"
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/road/routing/eta" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"waypoints\": [],
  \"dispatchId\": null,
  \"legId\": null,
  \"mode\": \"road\",
  \"transportMode\": \"TRUCK\",
  \"vehicleProfile\": null,
  \"departureAt\": null,
  \"maxAgeSeconds\": null,
  \"forceRefresh\": false,
  \"routeId\": null
}"
GET/api/road/routing/matrix
Auth requiredrouting.view

Lists routing matrix runs.

Requires features: routing.view

Parameters

NameInRequiredSchemaDescription
pagequeryNoany
pageSizequeryNoany
idsqueryNoany
statusqueryNoany
providerqueryNoany
sourcequeryNoany
confidencequeryNoany
linkedEntityTypequeryNoany
linkedEntityIdqueryNoany
sortFieldqueryNoany
sortDirqueryNoany

Responses

200Matrix runs returned
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "status": "completed",
      "provider": "HERE",
      "mode": "road",
      "source": "live",
      "confidence": "high",
      "degradedReasonCode": null,
      "linkedEntityType": null,
      "linkedEntityId": null,
      "originCount": 1,
      "destinationCount": 1,
      "cacheAgeSeconds": null,
      "requestedByUserId": null,
      "calculatedAt": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/road/routing/matrix?page=1&pageSize=25" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/routing/matrix
Auth requiredrouting.manage

Calculates a routing matrix for origin and destination points.

Requires features: routing.manage

Request body (application/json)

{
  "origins": [
    {
      "lat": 1,
      "lng": 1,
      "label": null,
      "address": null,
      "id": null
    }
  ],
  "destinations": [
    {
      "lat": 1,
      "lng": 1,
      "label": null,
      "address": null,
      "id": null
    }
  ],
  "linkedEntityType": null,
  "linkedEntityId": null,
  "mode": "road",
  "vehicleProfile": null,
  "departureAt": null,
  "maxAgeSeconds": null,
  "forceRefresh": false
}

Responses

201Matrix run created
Content-Type: application/json
{
  "matrixRun": {
    "id": "00000000-0000-4000-8000-000000000000",
    "status": "completed",
    "provider": "HERE",
    "mode": "road",
    "source": "live",
    "confidence": "high",
    "degradedReasonCode": null,
    "linkedEntityType": null,
    "linkedEntityId": null,
    "originCount": 1,
    "destinationCount": 1,
    "cacheAgeSeconds": null,
    "requestedByUserId": null,
    "calculatedAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "origins": [
      {
        "lat": 1,
        "lng": 1,
        "label": null,
        "address": null,
        "id": null
      }
    ],
    "destinations": [
      {
        "lat": 1,
        "lng": 1,
        "label": null,
        "address": null,
        "id": null
      }
    ],
    "rows": [
      {
        "originIndex": 1,
        "destinationIndex": 1,
        "distanceKm": 1,
        "durationMinutes": 1,
        "confidence": "high"
      }
    ],
    "requestSnapshot": {},
    "resultSnapshot": {
      "origins": [
        {
          "lat": 1,
          "lng": 1,
          "label": null,
          "address": null,
          "id": null
        }
      ],
      "destinations": [
        {
          "lat": 1,
          "lng": 1,
          "label": null,
          "address": null,
          "id": null
        }
      ],
      "cells": [
        {
          "originIndex": 1,
          "destinationIndex": 1,
          "distanceKm": 1,
          "durationMinutes": 1,
          "confidence": "high"
        }
      ],
      "source": "live",
      "confidence": "high",
      "degradedReasonCode": null
    }
  },
  "meta": {
    "cacheHit": true,
    "fallbackUsed": true
  }
}

Example

curl -X POST "https://api.open-mercato.local/api/road/routing/matrix" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"origins\": [
    {
      \"lat\": 1,
      \"lng\": 1,
      \"label\": null,
      \"address\": null,
      \"id\": null
    }
  ],
  \"destinations\": [
    {
      \"lat\": 1,
      \"lng\": 1,
      \"label\": null,
      \"address\": null,
      \"id\": null
    }
  ],
  \"linkedEntityType\": null,
  \"linkedEntityId\": null,
  \"mode\": \"road\",
  \"vehicleProfile\": null,
  \"departureAt\": null,
  \"maxAgeSeconds\": null,
  \"forceRefresh\": false
}"
GET/api/road/routing/matrix/{id}
Auth requiredrouting.view

Returns a routing matrix run with request and result snapshots.

Requires features: routing.view

Parameters

NameInRequiredSchemaDescription
idpathYesany

Responses

200Matrix run returned
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "status": "completed",
  "provider": "HERE",
  "mode": "road",
  "source": "live",
  "confidence": "high",
  "degradedReasonCode": null,
  "linkedEntityType": null,
  "linkedEntityId": null,
  "originCount": 1,
  "destinationCount": 1,
  "cacheAgeSeconds": null,
  "requestedByUserId": null,
  "calculatedAt": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "origins": [
    {
      "lat": 1,
      "lng": 1,
      "label": null,
      "address": null,
      "id": null
    }
  ],
  "destinations": [
    {
      "lat": 1,
      "lng": 1,
      "label": null,
      "address": null,
      "id": null
    }
  ],
  "rows": [
    {
      "originIndex": 1,
      "destinationIndex": 1,
      "distanceKm": 1,
      "durationMinutes": 1,
      "confidence": "high"
    }
  ],
  "requestSnapshot": {},
  "resultSnapshot": {
    "origins": [
      {
        "lat": 1,
        "lng": 1,
        "label": null,
        "address": null,
        "id": null
      }
    ],
    "destinations": [
      {
        "lat": 1,
        "lng": 1,
        "label": null,
        "address": null,
        "id": null
      }
    ],
    "cells": [
      {
        "originIndex": 1,
        "destinationIndex": 1,
        "distanceKm": 1,
        "durationMinutes": 1,
        "confidence": "high"
      }
    ],
    "source": "live",
    "confidence": "high",
    "degradedReasonCode": null
  }
}
404Matrix run not found
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/road/routing/matrix/:id" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/road/routing/provider-health
Auth requiredrouting.view

Returns routing provider capability and health status.

Requires features: routing.view

Parameters

NameInRequiredSchemaDescription
providerqueryNoany

Responses

200Provider health returned
Content-Type: application/json
{
  "items": [
    {
      "providerId": "HERE",
      "label": "string",
      "ok": true,
      "source": "live",
      "degradedReasonCode": null,
      "checkedAt": "string",
      "capabilities": [
        "route"
      ],
      "modes": [
        "road"
      ]
    }
  ]
}

Example

curl -X GET "https://api.open-mercato.local/api/road/routing/provider-health" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Road Tracking

Showing 3 of 3 endpoints
GET/api/road/tracking/live
Auth requiredroad_tracking.view

Returns the latest tracked position per vehicle for the current organization.

Requires features: road_tracking.view

Parameters

NameInRequiredSchemaDescription
vehicleIdsqueryNoany
providerqueryNoany
freshnessqueryNoany
includeTrailMinutesqueryNoany

Responses

200Live vehicle positions with geofence-ready location overlays.
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "vehicleId": "00000000-0000-4000-8000-000000000000",
      "driverId": null,
      "dispatchId": null,
      "legId": null,
      "latitude": 1,
      "longitude": 1,
      "coordinates": {
        "latitude": 1,
        "longitude": 1
      },
      "altitudeM": null,
      "speedKmh": null,
      "headingDeg": null,
      "source": "string",
      "accuracyM": null,
      "satellites": null,
      "hdop": null,
      "providerName": "string",
      "providerPayload": null,
      "recordedAt": "string",
      "receivedAt": "string",
      "createdAt": "string",
      "registrationPlate": null,
      "gpsProvider": null,
      "isActive": true,
      "driverName": null,
      "freshness": "fresh",
      "ageMinutes": 1,
      "trail": [
        {
          "latitude": 1,
          "longitude": 1,
          "recordedAt": "string"
        }
      ]
    }
  ],
  "geofenceLocations": [
    {
      "locationId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "latitude": 1,
      "longitude": 1,
      "geofenceRadiusM": 1
    }
  ],
  "generatedAt": "string"
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/road/tracking/live?includeTrailMinutes=30" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/road/tracking/position
Auth requiredroad_tracking.view

Creates a manual road tracking position report.

Requires features: road_tracking.view

Request body (application/json)

{
  "vehicleId": "00000000-0000-4000-8000-000000000000",
  "driverId": null,
  "dispatchId": null,
  "legId": null,
  "latitude": 1,
  "longitude": 1,
  "altitudeM": null,
  "speedKmh": null,
  "headingDeg": null,
  "source": "MANUAL",
  "accuracyM": null,
  "satellites": null,
  "hdop": null,
  "providerPayload": null
}

Responses

201Tracked position created.
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "vehicleId": "00000000-0000-4000-8000-000000000000",
  "driverId": null,
  "dispatchId": null,
  "legId": null,
  "latitude": 1,
  "longitude": 1,
  "coordinates": {
    "latitude": 1,
    "longitude": 1
  },
  "altitudeM": null,
  "speedKmh": null,
  "headingDeg": null,
  "source": "string",
  "accuracyM": null,
  "satellites": null,
  "hdop": null,
  "providerName": "string",
  "providerPayload": null,
  "recordedAt": "string",
  "receivedAt": "string",
  "createdAt": "string"
}
400Invalid payload
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/road/tracking/position" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"vehicleId\": \"00000000-0000-4000-8000-000000000000\",
  \"driverId\": null,
  \"dispatchId\": null,
  \"legId\": null,
  \"latitude\": 1,
  \"longitude\": 1,
  \"altitudeM\": null,
  \"speedKmh\": null,
  \"headingDeg\": null,
  \"source\": \"MANUAL\",
  \"accuracyM\": null,
  \"satellites\": null,
  \"hdop\": null,
  \"providerPayload\": null
}"
GET/api/road/tracking/vehicle/{id}/history
Auth requiredroad_tracking.view

Returns tracked position history for a single vehicle and time range.

Requires features: road_tracking.view

Parameters

NameInRequiredSchemaDescription
idpathYesany
fromqueryYesany
toqueryYesany
maxPointsqueryNoany

Responses

200Vehicle tracking history with replay summary.
Content-Type: application/json
{
  "vehicleId": "00000000-0000-4000-8000-000000000000",
  "registrationPlate": null,
  "points": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "vehicleId": "00000000-0000-4000-8000-000000000000",
      "driverId": null,
      "dispatchId": null,
      "legId": null,
      "latitude": 1,
      "longitude": 1,
      "coordinates": {
        "latitude": 1,
        "longitude": 1
      },
      "altitudeM": null,
      "speedKmh": null,
      "headingDeg": null,
      "source": "string",
      "accuracyM": null,
      "satellites": null,
      "hdop": null,
      "providerName": "string",
      "providerPayload": null,
      "recordedAt": "string",
      "receivedAt": "string",
      "createdAt": "string"
    }
  ],
  "stops": [
    {
      "startedAt": "string",
      "endedAt": "string",
      "durationMinutes": 1,
      "latitude": 1,
      "longitude": 1
    }
  ],
  "summary": {
    "pointCount": 1,
    "distanceKmEstimate": 1
  }
}
400Invalid query
Content-Type: application/json
{
  "error": "string"
}
404Vehicle not found
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X GET "https://api.open-mercato.local/api/road/tracking/vehicle/00000000-0000-4000-8000-000000000000/history?maxPoints=500" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"

Tariff Rates

Showing 5 of 5 endpoints
GET/api/route_planning/tariff-rates
Auth requiredroute_planning.view

List tariff rates

Paginated list of tariff rates with optional filtering by line category and provider type Requires features: route_planning.view

Responses

200Paginated tariff rate list
Content-Type: application/json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "lineCategory": "string",
      "ratePerTonKm": 1,
      "currency": "string",
      "validFrom": "string",
      "validTo": null,
      "providerType": "string",
      "infrastructureManager": null,
      "minCharge": null,
      "isActive": true,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Example

curl -X GET "https://api.open-mercato.local/api/route_planning/tariff-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/route_planning/tariff-rates
Auth requiredroute_planning.create

Create a tariff rate

Create a new tariff rate entry Requires features: route_planning.create

Request body (application/json)

{
  "name": "string",
  "lineCategory": "TRUNK",
  "ratePerTonKm": 1,
  "currency": "PLN",
  "validFrom": "2025-01-01T00:00:00.000Z",
  "validTo": null,
  "providerType": "PLK",
  "infrastructureManager": null,
  "minCharge": null,
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

201Tariff rate created
Content-Type: application/json
{
  "id": "00000000-0000-4000-8000-000000000000"
}

Example

curl -X POST "https://api.open-mercato.local/api/route_planning/tariff-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"name\": \"string\",
  \"lineCategory\": \"TRUNK\",
  \"ratePerTonKm\": 1,
  \"currency\": \"PLN\",
  \"validFrom\": \"2025-01-01T00:00:00.000Z\",
  \"validTo\": null,
  \"providerType\": \"PLK\",
  \"infrastructureManager\": null,
  \"minCharge\": null,
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"
PUT/api/route_planning/tariff-rates
Auth requiredroute_planning.update

Update a tariff rate

Update an existing tariff rate Requires features: route_planning.update

Request body (application/json)

{
  "id": "00000000-0000-4000-8000-000000000000",
  "currency": "PLN",
  "validTo": null,
  "infrastructureManager": null,
  "minCharge": null
}

Responses

200Tariff rate updated
Content-Type: application/json
{
  "ok": true
}

Example

curl -X PUT "https://api.open-mercato.local/api/route_planning/tariff-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"id\": \"00000000-0000-4000-8000-000000000000\",
  \"currency\": \"PLN\",
  \"validTo\": null,
  \"infrastructureManager\": null,
  \"minCharge\": null
}"
DELETE/api/route_planning/tariff-rates
Auth requiredroute_planning.delete

Delete a tariff rate

Soft-delete a tariff rate Requires features: route_planning.delete

Responses

200Tariff rate deleted
Content-Type: application/json
{
  "ok": true
}

Example

curl -X DELETE "https://api.open-mercato.local/api/route_planning/tariff-rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/route_planning/tariff-rates/calculate
Auth requiredroute_planning.calculate

Calculate route cost

Calculate transport cost between two stations using Dijkstra routing and applicable tariff rates Requires features: route_planning.calculate

Request body (application/json)

{
  "fromStationId": "00000000-0000-4000-8000-000000000000",
  "toStationId": "00000000-0000-4000-8000-000000000000",
  "grossWeightTonnes": 1,
  "organizationId": "00000000-0000-4000-8000-000000000000",
  "tenantId": "00000000-0000-4000-8000-000000000000"
}

Responses

200Route cost calculation result
Content-Type: application/json
{
  "route": {
    "path": [
      "00000000-0000-4000-8000-000000000000"
    ],
    "totalDistanceKm": 1
  },
  "segments": [
    {
      "segmentId": "00000000-0000-4000-8000-000000000000",
      "lineCategory": "string",
      "distanceKm": 1,
      "ratePerTonKm": 1,
      "cost": 1
    }
  ],
  "totalCost": 1,
  "currency": "string"
}
404No route found between stations
Content-Type: application/json
{
  "error": "string"
}

Example

curl -X POST "https://api.open-mercato.local/api/route_planning/tariff-rates/calculate" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{
  \"fromStationId\": \"00000000-0000-4000-8000-000000000000\",
  \"toStationId\": \"00000000-0000-4000-8000-000000000000\",
  \"grossWeightTonnes\": 1,
  \"organizationId\": \"00000000-0000-4000-8000-000000000000\",
  \"tenantId\": \"00000000-0000-4000-8000-000000000000\"
}"

ShippingCarriers

Showing 7 of 7 endpoints
POST/api/shipping-carriers/cancel
Auth requiredshipping_carriers.manage

Cancel shipment

Requires features: shipping_carriers.manage

Responses

200Shipment cancelled
Content-Type: application/json
"string"
422Validation failed or shipment cannot be cancelled in its current status
Content-Type: application/json
"string"
502Provider upstream error
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/shipping-carriers/cancel" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/shipping-carriers/points
Auth requiredshipping_carriers.view

Search carrier drop-off points (lockers, POP points)

Requires features: shipping_carriers.view

Responses

200Points returned
Content-Type: application/json
"string"
422Validation failed
Content-Type: application/json
"string"
502Provider upstream error or unsupported
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/shipping-carriers/points" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/shipping-carriers/providers
Auth requiredshipping_carriers.manage

List registered shipping providers

Requires features: shipping_carriers.manage

Responses

200List of registered provider keys
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/shipping-carriers/providers" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/shipping-carriers/rates
Auth requiredshipping_carriers.manage

Calculate shipping rates

Requires features: shipping_carriers.manage

Responses

200Rates calculated
Content-Type: application/json
"string"
422Validation failed
Content-Type: application/json
"string"
502Provider upstream error
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/shipping-carriers/rates" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/shipping-carriers/shipments
Auth requiredshipping_carriers.manage

Create shipment

Requires features: shipping_carriers.manage

Responses

201Shipment created
Content-Type: application/json
"string"
422Validation failed
Content-Type: application/json
"string"
502Provider upstream error
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/shipping-carriers/shipments" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
GET/api/shipping-carriers/tracking
Auth requiredshipping_carriers.view

Get tracking

Requires features: shipping_carriers.view

Responses

200Tracking returned
Content-Type: application/json
"string"
422Validation failed
Content-Type: application/json
"string"
502Provider upstream error
Content-Type: application/json
"string"

Example

curl -X GET "https://api.open-mercato.local/api/shipping-carriers/tracking" \
  -H "Accept: application/json" \
  -H "authorization: Bearer <token>"
POST/api/shipping-carriers/webhook/{provider}

Process inbound carrier webhook

Parameters

NameInRequiredSchemaDescription
providerpathYesany

Responses

202Webhook accepted for async processing
Content-Type: application/json
"string"
401Signature verification failed
Content-Type: application/json
"string"
404Unknown provider
Content-Type: application/json
"string"

Example

curl -X POST "https://api.open-mercato.local/api/shipping-carriers/webhook/:provider" \
  -H "Accept: application/json"