API Documentation¶

Depictio provides a comprehensive REST API that allows you to interact with all aspects of the platform programmatically. This section provides an overview of the API and links to detailed documentation.

Overview¶

The Depictio API enables you to:

Manage projects and workflows
Create and configure dashboards
Upload and retrieve data
Manage users and permissions

All API endpoints follow RESTful principles and use JWT authentication for security.

API Structure & Endpoints¶

The Depictio API is organized around the following main resources:

Projects - Manage top-level entities that encapsulate production-oriented pipelines/workflows
Workflows - Interact with standardized production-oriented workflows
Run Configurations - Define parameters and settings for workflow runs
Runs - Manage instances of workflow executions
Files - Access artifacts produced by workflow runs
Data Collections - Work with aggregated data from files following the same structure
Dashboards - Create and manage interactive visualization dashboards
Users - Handle user authentication and authorization
Jobs - Follow work the server finishes in the background (v1.15.0+)
Export - Serve one dashboard component to another website, as a Plotly spec or a self-contained page (v1.17.0+). See Component export

Authentication¶

All API requests require authentication using JWT (JSON Web Tokens). To authenticate:

Obtain a token by sending a POST request to the /auth/login endpoint with your credentials
Include the token in the Authorization header of subsequent requests using the format: Bearer <token>

API Versioning¶

The Depictio API uses versioning to ensure backward compatibility. The current version is v1, which is reflected in the URL path:

https://your-depictio-instance.com/depictio/api/v1/...

Jobs (v1.15.0+)¶

Some requests start work that outlives an HTTP request. They answer with a job_id, and the client polls the job until it ends. Paths are under /depictio/api/v1. The routes exist only when DEPICTIO_JOBS_ENABLED is true; otherwise /jobs answers 404. See Jobs.

Method and path	What it does
`GET /jobs/{job_id}`	One job: `status`, `step`, `detail`, `progress`, `result` or `error`, timestamps, and `poll_after_seconds`, the suggested wait before the next poll
`GET /jobs`	Your jobs, newest first. Filters `kind`, `status` and `project_id`; `limit` (1–200, default 50) and `skip`. Admins see everyone's
`POST /jobs/{job_id}/cancel`	Cancels a job that has not ended, and asks the worker to stop its task

A job is pending, running, success, failed or cancelled. A job that belongs to someone else answers 404, as a missing one does; admins can read any job. There is no route to create a job: the endpoint that owns the work creates it, and names its kind.

Kind	Created by
`deltatable.upsert`	`POST /deltatables/upsert` with `async_mode: true`, when offloading is on. Without it the response has no `job_id` and the work is done
`project.ingest`	`POST /projects/ingestion/trigger/{project_id}`, the Run ingestion button

The project page uses these routes for its ingestion tab:

Method and path	What it does
`GET /projects/ingestion-runs/{project_id}`	The project's ingestion runs, newest first, with `limit` and `skip`. Paths and host details are removed for viewers who cannot edit the project
`GET /projects/ingestion/trigger-status/{project_id}`	Whether Run ingestion is offered (`enabled`), usable by the caller (`available`), and the `reason` when it is not
`POST /projects/ingestion/trigger/{project_id}`	Starts an ingestion; `overwrite` as a query parameter. Returns `job_id`, `run_id` and `already_running`

GET /utils/capabilities lists jobs, deltatables.async_upsert and ingestion.browser_trigger in its features when each is turned on, so a client can check before relying on them.

In This Section¶

API Reference - Interactive API documentation generated from the OpenAPI specification

FastAPI Docs - Access to the auto-generated FastAPI documentation