API Guide
PROCESS API
Coordinate tenant-scoped workflows while each connected application remains authoritative for its own business records.
Authentication And Tenant Context
All PROCESS operations require an authenticated Velosity user and active tenant unless the operation is explicitly documented as anonymous. Send the Velosity API key in X-APIKEY, or use the supported browser or bearer-token identity flow. The API derives tenant and actor context from the credential; clients must not attempt to select another tenant through request data.
Process Identity And Domain Ownership
A process instance has a stable ProcessID and one primary EntityType/EntityID. Use that entity identity to connect the workflow to the authoritative quote, order, item, ticket, or request. PROCESS owns workflow state, assignments, evidence, and history; the connected application owns its domain record.
When a workflow relates to several external records, retain explicit relationships or correlation records. Do not infer links from names, timestamps, or descriptive text.
Discover And Start Processes
Use discovery to obtain definitions and active processes that apply to an entity and the current actor. Discovery is advisory: start and transition commands repeat authorization and current-state checks.
GET /v1/processes/discovery/{entityType}/{entityId}
POST /v1/processes/discovery/{entityType}/{entityId}/definitions/{definitionId}/startUse the returned ProcessID for subsequent workflow operations. Avoid permanently hardcoding a draft definition identifier; integrations should follow the approved definition-family and version policy.
Transitions, Tasks, Forms, And Evidence
Retrieve available transitions for the current process, then submit the selected transition with its expected state and idempotency key. PROCESS validates roles, required tasks, forms, approvals, and current state before committing the change.
GET /v1/processes/{processId}/transitions
POST /v1/processes/{processId}/transitions/{transitionId}/trigger
GET /v1/processes/{processId}/tasks
GET /v1/processes/{processId}/evidenceForm submissions and promoted process variables retain provenance. Do not update process state directly in a database or treat notification delivery as evidence that external work occurred.
Events, Callbacks, And Webhooks
Committed starts and transitions produce durable lifecycle events. Consumers must deduplicate by eventId. Authenticated authoritative events can be submitted to POST /v1/processes/events and may advance an eligible process when a configured mapping matches.
A webhook attempt reports delivery, not a business outcome. Use an authoritative event or authorized command to record a verified external result. Consult the generated reference before depending on a callback route; callback capabilities differ from lifecycle-event ingestion.
Idempotency, Ordering, And Reconciliation
- Assign every command or event a stable idempotency key.
- Assume at-least-once delivery and safely accept retries.
- Include occurrence time, correlation identity, and source revision or sequence when available.
- Reject or ignore events that are stale for the current process state.
- Reconcile PROCESS state and external-system records after outages or dead-letter delivery.
- Preserve the initiating user or service identity for authorization and audit.