API Overview¶

The Manifest Platform exposes a RESTful API for managing solutions, components, agents, workflows, connectors, datasets, hosted services, deployments, users, and organizations. All platform capabilities available through the web console are also available programmatically through this API.

Base URL¶

All API requests are made against a single base URL:

https://api.flow.marut.cloud

Every endpoint is prefixed with /api/v1/. For example, listing solutions:

GET https://api.flow.marut.cloud/api/v1/solutions

API Versioning¶

The API uses URL-based versioning. The current stable version is v1.

Version	Status	Base Path
`v1`	Current	`/api/v1/`

Versioning policy

Breaking changes (removed fields, changed semantics, renamed endpoints) will only be introduced in a new version. Additive changes (new fields, new endpoints) may be added to the current version without a version bump.

Authentication¶

Every request must include a valid credential. The API supports two authentication methods:

API KeyBearer Token

Pass your API key in the X-API-Key header:

curl -H "X-API-Key: fl_your_api_key_here" \
     https://api.flow.marut.cloud/api/v1/solutions

Pass a JWT bearer token in the Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
     https://api.flow.marut.cloud/api/v1/solutions

See the Authentication page for details on obtaining tokens, OAuth flows, and token refresh.

Common Headers¶

Include these headers with every request:

Header	Required	Description
`X-API-Key`	Yes (if no Bearer token)	Organization-scoped API key
`Authorization`	Yes (if no API key)	`Bearer <token>` for JWT authentication
`Content-Type`	Yes (for POST/PUT/PATCH)	`application/json` unless uploading files
`Accept`	No	`application/json` (default)
`X-Request-ID`	No	Client-generated UUID for request tracing. If omitted, the server generates one and returns it in the response.
`X-Workspace-ID`	No	Override the default workspace for the request

Request tracing

Always send an X-Request-ID header when debugging. The same ID appears in server logs, audit trails, and error responses, making it straightforward to trace a request end-to-end.

Error Response Format¶

All errors follow a consistent JSON structure:

{
  "code": "VALIDATION_ERROR",
  "message": "Request body failed validation.",
  "details": [
    {
      "field": "name",
      "issue": "Field is required."
    },
    {
      "field": "description",
      "issue": "Must be at most 500 characters."
    }
  ],
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Codes¶

HTTP Status	Code	Meaning
`400`	`VALIDATION_ERROR`	Request body or query parameters failed validation
`401`	`AUTHENTICATION_REQUIRED`	Missing or invalid credentials
`403`	`PERMISSION_DENIED`	Valid credentials but insufficient permissions
`404`	`NOT_FOUND`	Resource does not exist or is not visible to the caller
`409`	`CONFLICT`	Resource already exists or state conflict (e.g., duplicate slug)
`422`	`UNPROCESSABLE_ENTITY`	Semantically invalid request (e.g., deploying a draft component)
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Retry after the interval in `Retry-After` header.
`500`	`INTERNAL_ERROR`	Unexpected server error. Include the `request_id` when reporting.
`503`	`SERVICE_UNAVAILABLE`	Temporary outage. Retry with exponential backoff.

Rate Limiting¶

The API enforces rate limits per organization to ensure fair usage.

Tier	Requests per minute	Burst
Standard	600	100
Heavy (file uploads, deployments)	60	20
Gateway (AI model inference)	Governed by model-specific limits	--

Rate limit state is returned in response headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1711036800
Retry-After: 12

Handling rate limits

When you receive a 429 response, wait for the number of seconds indicated by the Retry-After header before retrying. Do not retry immediately in a tight loop.

Pagination¶

List endpoints return paginated results. Use limit and offset query parameters:

GET /api/v1/solutions?limit=25&offset=50

The response includes pagination metadata:

{
  "items": [...],
  "total": 142,
  "limit": 25,
  "offset": 50
}

Parameter	Type	Default	Max	Description
`limit`	integer	25	100	Number of items to return
`offset`	integer	0	--	Number of items to skip

SDK Clients¶

The Flow SDK provides typed Python clients that wrap this API. Use them instead of raw HTTP when possible:

Client	Use Case	Reference
FlowSDK	Code running inside hosted services and code blocks	Auto-generated reference
CLIClient	Invoking services from scripts and automation	Auto-generated reference
GatewayClient	Direct AI Gateway access for chat and embeddings	Auto-generated reference
PlatformClient	Low-level async platform API calls	Auto-generated reference

Next Steps¶

Authentication -- Detailed guide to API keys, OAuth, and token refresh
Endpoints -- Complete endpoint catalog organized by domain
FlowSDK -- Auto-generated SDK reference