Forjinn REST API: Complete Endpoint Reference

A complete reference for the Forjinn REST API. Build integrations, send messages to chatflows, manage agent flows, and automate document ingestion over HTTP.

The Forjinn REST API gives you programmatic access to every resource you can create and manage in the Forjinn UI. You can list and update chatflows, send prediction requests, ingest documents into a vector store, and configure scheduled or webhook-based triggers — all over standard HTTP.

All API responses use JSON. All request bodies that carry data must be sent as application/json unless you are uploading files, in which case multipart/form-data is accepted.

Base URL

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

For local development with a self-hosted instance:

http://localhost:3000/api/v1

Every endpoint documented in this reference is relative to this base URL. For example, GET /chatflows means:

GET https://your-forjinn-instance.com/api/v1/chatflows

API versioning

The current API version is v1, reflected in the /api/v1/ path prefix. Breaking changes will be introduced in a new version path (e.g., /api/v2/) rather than silently changing existing endpoints.

Request format

Set Content-Type: application/json on all requests with a body.
For file uploads (predictions with attachments, document-store upserts), use Content-Type: multipart/form-data.
Timestamps are returned as ISO 8601 strings (e.g., "2024-05-01T12:00:00.000Z").

Authentication

Most endpoints require an API key. Pass it as a Bearer token in the Authorization header, or as the apiKey query parameter. See Authentication for details.

Error responses

All errors follow a consistent JSON body format:

{
  "message": "Human-readable description of the error"
}

The HTTP status code tells you the class of error:

Status	Meaning
`400`	Bad Request — missing or malformed parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — your key does not have access to this resource
`404`	Not Found — the requested resource does not exist
`409`	Conflict — the operation conflicts with existing state
`412`	Precondition Failed — a required parameter was not provided
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — something went wrong on our side

Rate limiting

Forjinn enforces per-chatflow rate limits that are configurable in the UI. When a limit is exceeded the API returns 429 Too Many Requests. The specific limit values depend on how each chatflow is configured.

Pagination

Endpoints that return lists accept optional page and limit query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	The page number to return
`limit`	integer	`20`	Number of items per page

Example:

GET /api/v1/chatflows?page=2&limit=50