API Examples

Arcnem Vision exposes three primary operational APIs:

• a workflow/API-key ingestion path for automated uploads
• a service/API-key orchestration path for project-scoped service clients
• a dashboard/session path for operator-driven uploads, browsing, and workflow queueing

Agents can also connect through OAuth MCP to edit workflows, run experiments, and read project documents with scoped permissions.

Workflow-Key Ingestion

This is the automated path used by workflow-key clients or external integrations.

1. Get a presigned upload URL

curl -X POST http://localhost:3000/api/uploads/presign \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"contentType":"image/png","size":12345}'

2. Upload directly to storage

curl -X PUT "${UPLOAD_URL}" --data-binary @photo.png

3. Acknowledge the upload

curl -X POST http://localhost:3000/api/uploads/ack \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"objectKey":"uploads/.../photo.png"}'

After step 3, the API verifies the object, creates the document, and emits document/process.upload. The agents service loads the workflow key’s bound workflow and executes it.

Service API

The service API is the face-neutral orchestration surface for server-side clients.

Discover workflows

GET /api/service/workflows

Create a presigned upload

POST /api/service/uploads/presign

Body:

{
  "contentType": "image/png",
  "size": 12345,
  "visibility": "private"
}

Visibility is declared at presign time. ack simply confirms the uploaded object and materializes the document.

Acknowledge the upload

POST /api/service/uploads/ack

Body:

{
  "objectKey": "uploads/.../service-api/.../image.png",
  "idempotencyKey": "capture-42-ack"
}

Queue a workflow execution

POST /api/service/workflow-executions

Body:

{
  "workflowId": "<agentGraphId>",
  "documentIds": ["<documentId>"],
  "idempotencyKey": "capture-42-extraction-1",
  "initialState": {
    "analysis_label": "orbit"
  }
}

idempotencyKey is optional for compatibility. When supplied, it is scoped to the authenticated service key and endpoint. An identical retry returns the original response. Reusing it with different input returns 409.

You can also select documents by scope:

{
  "workflowId": "<agentGraphId>",
  "scope": {
    "apiKeyBound": false
  }
}

Inspect an execution

GET /api/service/workflow-executions/:id

List or read documents

GET /api/service/documents?limit=20&apiKeyBound=false
GET /api/service/documents/:id

Change document visibility

POST /api/service/documents/visibility

Body:

{
  "documentIds": ["<documentId>"],
  "visibility": "public"
}

OpenAPI

GET /api/openapi.json

This spec is generated from the shared service contracts so the public surface and the implementation stay aligned.

Dashboard Uploads

Dashboard uploads are session-authenticated and intended for operator-driven review.

Presign an ad-hoc upload

POST /api/dashboard/documents/uploads/presign

Body:

{
  "projectId": "<projectId>",
  "contentType": "image/png",
  "size": 12345
}

Acknowledge the ad-hoc upload

POST /api/dashboard/documents/uploads/ack

Body:

{
  "objectKey": "uploads/.../dashboard/.../image.png"
}

This creates the document and publishes a dashboard document event. Unlike the workflow-key path, it does not auto-run a workflow. Operators choose which saved workflow to queue next.

Queue Any Workflow Against A Saved Document

POST /api/dashboard/documents/:id/run

Body:

{
  "workflowId": "<agentGraphId>"
}

Response:

{
  "status": "queued",
  "documentId": "<documentId>",
  "workflowId": "<agentGraphId>",
  "workflowName": "OCR Review Supervisor"
}

This lets operators compare workflows, rerun analysis, or process dashboard-uploaded documents without changing a workflow key’s default assignment.

Auth Model

• Workflow ingestion uses API keys scoped to organization and project, with a direct agentGraphId binding.
• Service orchestration uses API keys scoped to organization and project.
• API keys are stored as SHA-256 hashes.
• Dashboard operations use better-auth session cookies.
• Local debug mode can bootstrap a seeded session when API_DEBUG=true.

Dashboard Document APIs

Browse or search documents

GET /api/dashboard/documents?organizationId=<orgId>&query=<text>&limit=<n>&cursor=<id>

Notes:

• organizationId is only needed when there is no authenticated dashboard session context.
• query is optional.
• Search always includes lexical ranking.
• When DOCUMENT_SEARCH_MODE=hybrid, the API also blends in semantic description matches when embeddings are available.

Response fields include:

• id
• objectKey
• contentType
• sizeBytes
• createdAt
• description
• thumbnailUrl
• distance

Read OCR outputs for a document

GET /api/dashboard/documents/:id/ocr

Each OCR result includes:

• ocrResultId
• ocrCreatedAt
• modelLabel
• text
• avgConfidence
• result

Read segmentation outputs for a document

GET /api/dashboard/documents/:id/segmentations

Each segmentation result includes:

• segmentationId
• segmentationCreatedAt
• modelLabel
• prompt
• nested derived document data when a segmented image was stored

Grounded Collection Chat

POST /api/dashboard/documents/chat

Notes:

• Dashboard auth is session-based and scoped to the active organization.
• The request body follows the TanStack AI chat shape.
• The current UI uses organization scope, while the endpoint also accepts optional projectIds, apiKeyIds, and documentIds.
• Responses stream over Server-Sent Events.
• Source cards are emitted as assistant_sources events and include document metadata plus matched excerpts.
• The dashboard bundle proxies this endpoint locally at /api/documents/chat.

The chat layer is grounded in stored document descriptions, OCR text, and related segmentation context.

Dashboard Realtime Feed

GET /api/dashboard/realtime

This Server-Sent Events feed publishes:

• document creation
• OCR creation
• description upserts
• segmentation creation
• run creation
• run step changes
• run completion

The dashboard bundle proxies this feed locally at /api/realtime/dashboard to power the live Docs and Runs tabs.

Health Checks

GET http://localhost:3000/health   # API
GET http://localhost:3020/health   # Agents
GET http://localhost:3021/health   # MCP