Quantra Docs — API Reference

API Reference

The Quantra platform exposes a comprehensive REST API built on the Django web framework. The API serves as the backbone for all interactions between the web-based user interface and the backend, and it can also be used for programmatic integration with external systems. All requests and responses use JSON encoding unless otherwise specified.

REST API Overview

The Quantra REST API comprises 111 routes organized across authentication, project management, canvas manipulation, pipeline execution, administration, and plugin-specific endpoints. The API follows standard REST conventions: resources are identified by URLs, HTTP methods indicate the action (GET for retrieval, POST for creation, PUT for updates, DELETE for removal), and HTTP status codes communicate the result of each operation.

Base URL

All API endpoints are served from the Quantra web application, which listens on port 4443 by default over HTTPS:

https://your-quantra-host:4443/

Request Format

For endpoints that accept a request body (POST, PUT), the body must be valid JSON with the Content-Type: application/json header. File upload endpoints accept multipart/form-data instead.

Response Format

All responses return JSON. Successful responses use HTTP 200 (OK) or 201 (Created). Error responses include a JSON object with an error field describing the issue and an appropriate HTTP status code (400, 401, 403, 404, 500).

Authentication Endpoints

POST /login

Authenticates a user with email and password credentials.

Field	Type	Description
`email`	string	The user's registered email address.
`password`	string	The user's password.

Request:

POST /login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "securepassword123"
}

Response (success, no MFA):

HTTP 200 OK
{
    "status": "success",
    "user": {
        "email": "user@example.com",
        "first_name": "Jane",
        "last_name": "Doe"
    }
}

Response (MFA required):

HTTP 200 OK
{
    "status": "mfa_required",
    "message": "Please provide your MFA code."
}

POST /mfa/verify

Verifies a TOTP code during the MFA step of the login flow. Must be called after a successful /login that returned mfa_required.

Field	Type	Description
`code`	string	The 6-digit TOTP code from the user's authenticator app.

Request:

POST /mfa/verify
Content-Type: application/json

{
    "code": "482901"
}

Response:

HTTP 200 OK
{
    "status": "success",
    "message": "MFA verification successful."
}

POST /logout

Invalidates the current session and logs the user out. No request body is required. The session cookie is cleared on the server side.

POST /logout

HTTP 200 OK
{
    "status": "success",
    "message": "Logged out successfully."
}

Project Endpoints

GET /projects

Returns a list of all projects accessible to the authenticated user. This includes projects the user owns and projects that have been shared with them.

HTTP 200 OK
{
    "projects": [
        {
            "id": 1,
            "name": "Invoice Processing Pipeline",
            "owner": "admin@example.com",
            "created_at": "2025-03-10T09:15:00Z",
            "updated_at": "2025-06-12T14:30:00Z",
            "description": "Automated invoice data extraction and validation."
        },
        {
            "id": 2,
            "name": "Contract Analysis",
            "owner": "admin@example.com",
            "created_at": "2025-04-22T11:00:00Z",
            "updated_at": "2025-06-14T16:45:00Z",
            "description": "Extract key clauses and dates from legal contracts."
        }
    ]
}

POST /projects

Creates a new project. The authenticated user becomes the owner.

Field	Type	Required	Description
`name`	string	Yes	The project name.
`description`	string	No	A description of the project's purpose.

GET /projects/{id}

Returns the details of a specific project, including its full canvas (nodes and edges), if the user has at least Read permission.

PUT /projects/{id}

Updates a project's name or description. Requires Write permission.

DELETE /projects/{id}

Permanently deletes a project and all associated nodes, edges, and execution history. Requires ownership or Write permission. This action is irreversible.

POST /projects/{id}/share

Shares a project with another user at a specified permission level.

Field	Type	Description
`email`	string	The email of the user to share with.
`permission_level`	string	One of: `read`, `execute`, `write`.

Canvas Endpoints

The canvas represents the visual pipeline editor. Nodes are the processing steps (datasources, tools, workbenches) and edges are the connections between them.

GET /projects/{id}/nodes

Returns all nodes on the canvas for the specified project.

HTTP 200 OK
{
    "nodes": [
        {
            "id": 12,
            "node_type": "datasource",
            "plugin_id": "file_upload",
            "label": "Upload Documents",
            "x_pos": 100,
            "y_pos": 200,
            "config": {"accepted_types": [".pdf", ".docx"]},
            "created_at": "2025-06-01T10:00:00Z"
        },
        {
            "id": 13,
            "node_type": "tool",
            "plugin_id": "ocr_tool",
            "label": "OCR Extraction",
            "x_pos": 400,
            "y_pos": 200,
            "config": {"engine": "trocr", "language": "en"},
            "created_at": "2025-06-01T10:05:00Z"
        }
    ]
}

POST /projects/{id}/nodes

Adds a new node to the canvas. Requires Write permission.

Field	Type	Description
`node_type`	string	One of: `datasource`, `tool`, `workbench`.
`plugin_id`	string	The identifier of the plugin to use for this node.
`label`	string	Display label for the node.
`x_pos`	integer	Horizontal position on the canvas.
`y_pos`	integer	Vertical position on the canvas.
`config`	object	Plugin-specific configuration as a JSON object.

PUT /nodes/{id}

Updates an existing node's label, position, or configuration.

DELETE /nodes/{id}

Removes a node from the canvas. Any edges connected to this node are also removed.

GET /projects/{id}/edges

Returns all edges for the specified project.

HTTP 200 OK
{
    "edges": [
        {
            "id": 5,
            "source_node": 12,
            "target_node": 13,
            "edge_mode": "flow"
        }
    ]
}

POST /projects/{id}/edges

Creates a new edge between two nodes.

Field	Type	Description
`source_node`	integer	The ID of the source node.
`target_node`	integer	The ID of the target node.
`edge_mode`	string	One of: `flow`, `interactive`, `reference`.

Execution Endpoints

POST /projects/{id}/run

Initiates a pipeline execution for the specified project. The platform performs a topological sort of the canvas graph, constructs the CNO chain JSON, and begins executing nodes in dependency order. Requires Execute or Write permission.

HTTP 202 Accepted
{
    "execution_id": 47,
    "status": "running",
    "message": "Pipeline execution started."
}

GET /executions/{id}

Returns the current status and metadata of a specific execution.

HTTP 200 OK
{
    "id": 47,
    "project_id": 1,
    "status": "completed",
    "started_at": "2025-06-15T10:00:00Z",
    "completed_at": "2025-06-15T10:02:34Z",
    "initiated_by": "admin@example.com"
}

GET /executions/{id}/results

Returns the result data from a completed execution, including the output from each node in the pipeline.

Administration Endpoints

GET /users

Returns a list of all user accounts. Requires staff privileges.

POST /users

Creates a new user account. Requires staff privileges.

Field	Type	Description
`email`	string	The new user's email address (used as login).
`first_name`	string	The user's first name.
`last_name`	string	The user's last name.
`password`	string	Initial password for the account.
`is_staff`	boolean	Whether the user has admin privileges.

GET /audit-logs

Returns audit log entries with optional filtering. Requires staff privileges. Supports query parameters: event_type, user, from_date, to_date, ip_address.

GET /settings

Returns the current system settings (session timeout, max login attempts, MFA requirement). Requires staff privileges.

PUT /settings

Updates system settings. Requires staff privileges.

GET /service-endpoints

Returns all registered microservice endpoints with their host, port, protocol, and active status. Useful for monitoring the health and availability of the microservice mesh.

CNO Chain JSON Format

When a pipeline is executed, the platform constructs a CNO (Canvas Node Orchestration) chain JSON document that describes the execution graph. This JSON is passed to the execution engine, which processes nodes in topological order. The chain JSON is also stored in the chain_json field of the GraphExecution model for auditability and replay.

Structure

{
    "contract": "quantra-cno-v1",
    "http_stream": "https://your-quantra-host:4443/stream/execution/47",
    "start": "node_12",
    "nodes": {
        "node_12": {
            "type": "datasource",
            "plugin_id": "file_upload",
            "label": "Upload Documents",
            "config": {
                "accepted_types": [".pdf", ".docx"],
                "source_path": "/data/incoming/"
            },
            "next": ["node_13"]
        },
        "node_13": {
            "type": "tool",
            "plugin_id": "ocr_tool",
            "label": "OCR Extraction",
            "config": {
                "engine": "trocr",
                "language": "en"
            },
            "next": ["node_14"]
        },
        "node_14": {
            "type": "tool",
            "plugin_id": "pii_redaction",
            "label": "Redact PII",
            "config": {
                "entities": ["name", "email", "phone", "address"]
            },
            "next": []
        }
    },
    "edges": [
        {"source": "node_12", "target": "node_13", "mode": "flow"},
        {"source": "node_13", "target": "node_14", "mode": "flow"}
    ]
}

Key Fields

Field	Type	Description
`contract`	string	Schema version identifier for the chain JSON format.
`http_stream`	string	URL for streaming execution progress back to the web client.
`start`	string	The identifier of the first node to execute (the root of the DAG).
`nodes`	object	A map of node identifiers to their configuration objects.
`edges`	array	An array of edge objects defining the connections and their modes.

gRPC Streaming Protocol

Microservices in Quantra communicate using gRPC with bidirectional streaming. The protocol is defined in a shared microservice.proto file.

Service Definition

service MicroService {
    rpc Call (stream MicroserviceCallRequest) returns (stream MicroserviceCallResponse);
}

Both the request and response are streams, enabling chunked data transfer for large documents. The client (Quantra platform) sends one or more request frames, and the microservice responds with one or more response frames. The final frame in a response stream is marked with eos: true (end of stream).

Standard Frame Format

All data exchanged between the platform and microservices follows a standard frame format, serialized as JSON within the gRPC message payload:

{
    "oauth2": {
        "url": null
    },
    "data": [
        {
            "meta": {
                "filename": "invoice_001.pdf",
                "page": 1,
                "total_pages": 3
            },
            "content": {
                "text": "Invoice Number: INV-2025-0042\nDate: 2025-06-15\nAmount: $1,250.00"
            }
        }
    ],
    "tod": "object",
    "eos": false
}

Frame Fields

Field	Type	Description
`oauth2`	object	OAuth2 context. Contains a `url` field, typically `null` for internal services. Used when a microservice needs to redirect to an external OAuth2 provider.
`data`	array	Array of data items. Each item has a `meta` object (arbitrary metadata) and a `content` object (the actual payload).
`tod`	string	Type of data. Either `"object"` (unstructured/document data) or `"table"` (structured tabular data).
`eos`	boolean	End of stream flag. Set to `true` on the final frame in a response sequence. Set to `false` on all intermediate frames.

Streaming behavior: Microservices can send multiple frames with eos: false to provide incremental results or progress updates. The platform collects all frames and assembles the complete result when it receives the frame with eos: true. This enables real-time progress feedback for long-running operations like OCR processing of multi-page documents.

Version Endpoints

Quantra exposes version information for the platform, plugins, and microservices through dedicated endpoints.

GET /version

Returns the current version of the Quantra platform.

HTTP 200 OK
{
    "platform": "1.0.42",
    "api_version": "v1"
}

GET /service-endpoints

In addition to connection details, the service endpoints response includes version information for each registered microservice, allowing administrators to verify that all services are running compatible versions.

Error Responses

All API errors follow a consistent format:

HTTP 403 Forbidden
{
    "error": "You do not have permission to access this project.",
    "code": "PERMISSION_DENIED"
}

Common Error Codes

HTTP Status	Code	Description
400	`BAD_REQUEST`	The request body is malformed or missing required fields.
401	`UNAUTHORIZED`	Authentication is required but no valid session exists.
403	`PERMISSION_DENIED`	The user does not have sufficient permissions for this action.
404	`NOT_FOUND`	The requested resource does not exist.
429	`RATE_LIMITED`	Too many requests; rate limit exceeded.
500	`INTERNAL_ERROR`	An unexpected server error occurred.