Flowintel, an open-source case management platform

REST API

The API supports case management, templates, integrations and administration. Open /api/ on your Flowintel instance for the combined Swagger interface. The OpenAPI document is available at /api/swagger.json. Older per-service /api/case/doc-style links are not the current documentation entry point.

Authentication

Most endpoints require a user’s API key in the X-API-KEY header. The key acts with that user’s role, specialised permissions and case access. Obtain your key from your account settings and keep it out of source code and logs.

The examples below assume these shell variables are set:

export FLOWINTEL_URL='http://127.0.0.1:7006'
# Set FLOWINTEL_API_KEY to your user API key in your local environment.

Use the HTTPS address of your deployment for remote requests. Alert ingestion is an exception: it authenticates with a connector key, described under Incoming alerts.

Case

Create a case:

curl --fail-with-body \
  -H "X-API-KEY: $FLOWINTEL_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Domain investigation","description":"Triage the report"}' \
  "$FLOWINTEL_URL/api/case/create"

A successful creation returns HTTP 201 with a case_id. Use that value for subsequent requests.

MethodPathPurpose
GET/api/case/allList cases available to the caller.
GET/api/case/{case_id}Retrieve a case.
POST/api/case/createCreate a case.
POST/api/case/{case_id}/editUpdate case fields.
GET/api/case/{case_id}/tasksList tasks in a case.
GET/api/case/{case_id}/historyRead case history.

Creation supports contextual tags, clusters, custom tags, deadlines, is_private and privileged_case. Setting the privileged flag requires the corresponding administrative permission. Consult Swagger for field details and the endpoints available in your deployed version.

Task

Replace 123 with the returned case ID:

curl --fail-with-body \
  -H "X-API-KEY: $FLOWINTEL_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Triage the report","description":"Record the evidence"}' \
  "$FLOWINTEL_URL/api/case/123/create_task"

Success returns HTTP 201 and a task_id. Task creation is under the case namespace; subsequent operations use /api/task/{task_id} and its subroutes for notes, assignment, files, subtasks and status changes.

Use /api/task/list_status to discover task statuses rather than hard-coding IDs from another instance. Privileged-case review rules also apply to API operations.

Python example

This example creates a case and then a task, checks HTTP errors and uses bounded request timeouts. It requires the requests package.

import os
import requests

base = os.environ["FLOWINTEL_URL"].rstrip("/")
with requests.Session() as session:
    session.headers["X-API-KEY"] = os.environ["FLOWINTEL_API_KEY"]
    response = session.post(
        f"{base}/api/case/create",
        json={"title": "Domain investigation from Python"},
        timeout=30,
    )
    response.raise_for_status()
    case_id = response.json()["case_id"]

    response = session.post(
        f"{base}/api/case/{case_id}/create_task",
        json={"title": "Review the evidence"},
        timeout=30,
    )
    response.raise_for_status()
    print(response.json())

Choose a unique title when rerunning the example. If a write times out, check whether it succeeded before retrying; creating a case and creating its task are separate operations.

Admin

/api/admin exposes user, organisation and role management. Examples include GET /api/admin/users, GET /api/admin/orgs and GET /api/admin/roles. Permissions vary by operation; user management also checks organisation-administrator scope where supported.

Templating

/api/templating manages case and task templates, their context and reusable work items. Template maintenance requires Template Editor permission or administrator access. For exchanging exported templates, use POST /api/importer/template.

Analyser

Start a session with POST /api/analyzer/misp-modules/query using a JSON body containing:

  • query: list of values to analyse.
  • input: one MISP attribute type.
  • modules: list of module names compatible with that input.

Use the returned session identifier with GET /api/analyzer/misp-modules/status/{session_id} and then GET /api/analyzer/misp-modules/result/{session_id}. Module execution is asynchronous; inspect status and result messages rather than treating the initial response as the final analysis.

Importer

POST /api/importer/case accepts Flowintel case JSON; POST /api/importer/template accepts template JSON. See Import and export before constructing payloads. POST /api/case_from_misp/ creates a case from a configured MISP instance/event and template.

Other services

PrefixPurpose
/api/connectorsConnector and instance management
/api/custom_tagsLocal tags
/api/my_assignmentAssigned work
/api/calendarCalendar operations
/api/alertsIncoming alert schema and ingestion

MISP sync settings and conflict resolution are exposed under /api/case/{case_id}/connectors/{link_id}/…. The settings response lists supported intervals, conflict strategies and resolutions.

Errors and automation

Read both the HTTP status and response body. Typical outcomes include 400 for invalid input, 403 for authentication/permission failures, and 404 for unavailable resources. Some legacy operations report errors in a JSON message even when the HTTP response is successful, particularly imports; validate the operation’s result too.

Some existing routes mutate data through GET requests. Check the documented method and operation before calling a route; do not indiscriminately crawl authenticated API URLs. Limit retries of writes and verify the existing state after a timeout.