Endpoint Catalog
This page lists all available API endpoints organized by domain. Every endpoint requires authentication (see Authentication). All paths are relative to the base URL https://api.flow.marut.cloud/api/v1/.
For typed Python clients that wrap these endpoints, see the SDK reference: FlowSDK, CLIClient, GatewayClient, PlatformClient.
Solutions
Manage top-level solutions that group components, agents, and workflows into deployable units.
| Method |
Path |
Description |
GET |
/solutions |
List all solutions in the current workspace |
POST |
/solutions |
Create a new solution |
GET |
/solutions/{solution_id} |
Get solution details |
PUT |
/solutions/{solution_id} |
Update a solution |
DELETE |
/solutions/{solution_id} |
Delete a solution |
GET |
/solutions/{solution_id}/components |
List components in a solution |
POST |
/solutions/{solution_id}/components |
Add a component to a solution |
POST |
/solutions/{solution_id}/deploy |
Deploy a solution to a ring |
Components
Manage individual components (agents, workflows, code blocks, tools, models, prompts, schemas, transforms, validations, states, and observability specs).
| Method |
Path |
Description |
GET |
/components |
List all components (filterable by type) |
POST |
/components |
Create a new component |
GET |
/components/{component_id} |
Get component details |
PUT |
/components/{component_id} |
Update a component |
DELETE |
/components/{component_id} |
Delete a component |
GET |
/components/{component_id}/versions |
List component versions |
POST |
/components/{component_id}/versions |
Create a new version |
POST |
/components/{component_id}/publish |
Publish a component version |
Agents
Build, configure, and execute AI agents.
| Method |
Path |
Description |
GET |
/agents |
List all agents |
POST |
/agents |
Create a new agent |
GET |
/agents/{agent_id} |
Get agent configuration |
PUT |
/agents/{agent_id} |
Update agent configuration |
DELETE |
/agents/{agent_id} |
Delete an agent |
POST |
/agents/{agent_id}/execute |
Execute an agent (synchronous) |
POST |
/agents/{agent_id}/execute/stream |
Execute an agent with SSE streaming |
GET |
/agents/{agent_id}/tools |
List tools available to an agent |
PUT |
/agents/{agent_id}/tools |
Update tool assignments for an agent |
GET |
/agents/{agent_id}/experiments |
List agent experiments |
POST |
/agents/{agent_id}/experiments |
Create an experiment run |
Workflows
Design, manage, and execute workflow DAGs.
| Method |
Path |
Description |
GET |
/workflows |
List all workflows |
POST |
/workflows |
Create a new workflow |
GET |
/workflows/{workflow_id} |
Get workflow definition |
PUT |
/workflows/{workflow_id} |
Update workflow definition |
DELETE |
/workflows/{workflow_id} |
Delete a workflow |
POST |
/workflows/{workflow_id}/execute |
Execute a workflow |
GET |
/workflows/{workflow_id}/executions |
List workflow executions |
GET |
/workflows/{workflow_id}/executions/{execution_id} |
Get execution details and status |
POST |
/workflows/{workflow_id}/executions/{execution_id}/cancel |
Cancel a running execution |
Connectors
Manage connector definitions and instances for external system integration.
| Method |
Path |
Description |
GET |
/connectors |
List available connector types |
GET |
/connectors/{connector_id} |
Get connector type details |
GET |
/connectors/{connector_id}/instances |
List connector instances |
POST |
/connectors/{connector_id}/instances |
Create a connector instance |
GET |
/connectors/{connector_id}/instances/{instance_id} |
Get instance details |
PUT |
/connectors/{connector_id}/instances/{instance_id} |
Update instance configuration |
DELETE |
/connectors/{connector_id}/instances/{instance_id} |
Delete a connector instance |
POST |
/connectors/{connector_id}/instances/{instance_id}/test |
Test instance connectivity |
POST |
/connectors/{connector_id}/instances/{instance_id}/operations/{operation_id}/execute |
Execute a connector operation |
Datasets
Query and manage structured datasets backed by connector instances. All paths are under /orgs/{org_id}/workspaces/{workspace_id}/datasets.
| Method |
Path |
Description |
POST |
/datasets/validate |
Validate dataset metadata without persisting |
GET |
/datasets |
List all datasets |
POST |
/datasets |
Create a new dataset |
GET |
/datasets/{dataset_id} |
Get dataset details |
PATCH |
/datasets/{dataset_id} |
Update dataset metadata |
DELETE |
/datasets/{dataset_id} |
Delete a dataset (soft delete) |
GET |
/datasets/{dataset_id}/schema |
Get current dataset schema |
GET |
/datasets/{dataset_id}/schema/history |
Get schema version history |
POST |
/datasets/{dataset_id}/schema |
Register a new schema version |
GET |
/datasets/{dataset_id}/lineage |
Get upstream/downstream lineage graph |
POST |
/datasets/{dataset_id}/publish |
Promote dataset to published status |
POST |
/datasets/{dataset_id}/certify |
Update dataset certification level |
POST |
/datasets/{dataset_id}/prepare |
Trigger dataset preparation (format conversion) |
Vector Indexes
Manage pgvector indexes for semantic search. All paths are under /orgs/{org_id}/vector.
| Method |
Path |
Description |
POST |
/vector/indexes |
Create a new vector index |
GET |
/vector/indexes |
List all vector indexes |
GET |
/vector/indexes/{index_id} |
Get index details |
DELETE |
/vector/indexes/{index_id} |
Delete a vector index |
POST |
/vector/indexes/{index_id}/upsert |
Insert or update vectors in the index |
POST |
/vector/indexes/{index_id}/search |
Semantic similarity search |
POST |
/vector/indexes/{index_id}/delete |
Delete specific vectors by ID |
CreateIndexRequest
| Field |
Type |
Required |
Description |
name |
string |
Yes |
Index name (1-200 chars) |
dimensions |
integer |
Yes |
Vector dimensionality (1-4096) |
metric |
string |
No |
Distance metric: cosine (default), l2, inner_product |
workspace_id |
UUID |
No |
Scope index to a specific workspace |
description |
string |
No |
Human-readable description |
embedding_model |
string |
No |
Model used to generate embeddings (e.g., text-embedding-3-small) |
metadata_schema |
object |
No |
JSON schema for vector metadata fields |
UpsertRequest
| Field |
Type |
Required |
Description |
vectors |
array |
Yes |
List of vector objects to insert or update |
vectors[].id |
string |
No |
Stable identifier; auto-generated if omitted |
vectors[].embedding |
float[] |
Yes |
The embedding vector |
vectors[].content |
string |
No |
Source text for the vector |
vectors[].metadata |
object |
No |
Arbitrary metadata for filtering |
SearchRequest
| Field |
Type |
Required |
Description |
query_embedding |
float[] |
Yes |
Query vector to search against |
top_k |
integer |
No |
Number of results to return (default: 10, max: 1000) |
filter_metadata |
object |
No |
Metadata key/value pairs to pre-filter candidates |
Hosted Services
Manage hosted services, endpoints, versions, and async jobs.
| Method |
Path |
Description |
GET |
/hosted-services |
List all hosted services |
POST |
/hosted-services |
Create a new hosted service |
GET |
/hosted-services/{service_id} |
Get service details |
PUT |
/hosted-services/{service_id} |
Update service configuration |
DELETE |
/hosted-services/{service_id} |
Delete a hosted service |
POST |
/hosted-services/{service_id}/publish |
Publish the current draft version |
GET |
/hosted-services/{service_id}/versions |
List service versions |
GET |
/hosted-services/{service_id}/openapi.json |
Get auto-generated OpenAPI spec |
Service Endpoints
| Method |
Path |
Description |
GET |
/hosted-services/{service_id}/endpoints |
List endpoints for a service |
POST |
/hosted-services/{service_id}/endpoints |
Register a new endpoint |
PUT |
/hosted-services/{service_id}/endpoints/{endpoint_id} |
Update an endpoint |
DELETE |
/hosted-services/{service_id}/endpoints/{endpoint_id} |
Remove an endpoint |
Service Gateway (Invocation)
| Method |
Path |
Description |
* |
/orgs/{org_id}/services/{service_id}/{path} |
Invoke a service endpoint (sync) |
* |
/orgs/{org_id}/services/{service_id}/v{version}/{path} |
Invoke a specific version |
POST |
/orgs/{org_id}/services/{service_id}/async/{path} |
Submit an async job |
Async Jobs
| Method |
Path |
Description |
GET |
/hosted-services/{service_id}/jobs/{job_id} |
Poll job status |
POST |
/hosted-services/{service_id}/jobs/batch |
Batch status check |
POST |
/hosted-services/{service_id}/jobs/{job_id}/cancel |
Cancel a job |
Deployments
Manage deployment rings and promote workflows across environments. All paths are under /orgs/{org_id}/workspaces/{workspace_id}/deployments.
Workflow Deployments
| Method |
Path |
Description |
GET |
/deployments |
List all deployments |
POST |
/deployments |
Deploy a workflow to a ring |
GET |
/deployments/{deployment_id} |
Get deployment details |
POST |
/deployments/{deployment_id}/promote |
Promote deployment to another ring |
POST |
/deployments/{deployment_id}/rollback |
Roll back to a previous deployment |
Approve/reject not yet wired
The promotion approval service layer exists but POST /{promotion_id}/approve and POST /{promotion_id}/reject endpoints are not yet registered in the router.
Rings
| Method |
Path |
Description |
POST |
/deployments/rings |
Create a deployment ring |
GET |
/deployments/rings |
List all rings |
GET |
/deployments/rings/{ring_id} |
Get ring details |
PUT |
/deployments/rings/{ring_id} |
Update ring configuration |
DELETE |
/deployments/rings/{ring_id} |
Delete a ring |
AI Gateway
Access AI models for chat completion, embeddings, and other inference tasks.
| Method |
Path |
Description |
POST |
/gateway/v1/chat/completions |
Chat completion (OpenAI-compatible) |
POST |
/gateway/v1/embeddings |
Generate embeddings |
GET |
/gateway/v1/models |
List available models |
GET |
/gateway/v1/models/{model_id} |
Get model details |
OpenAI-compatible
The AI Gateway endpoints follow the OpenAI API format. Existing OpenAI client libraries can be pointed at the gateway by changing the base URL and API key.
Users
Manage users within the organization.
| Method |
Path |
Description |
GET |
/users |
List organization users |
POST |
/users/invite |
Invite a new user |
GET |
/users/{user_id} |
Get user details |
PUT |
/users/{user_id} |
Update user profile or role |
DELETE |
/users/{user_id} |
Remove a user from the organization |
GET |
/users/me |
Get the current authenticated user |
Organizations
Manage organization settings, workspaces, and billing.
| Method |
Path |
Description |
GET |
/organizations |
List organizations the user belongs to |
GET |
/organizations/{org_id} |
Get organization details |
PUT |
/organizations/{org_id} |
Update organization settings |
GET |
/organizations/{org_id}/workspaces |
List workspaces |
POST |
/organizations/{org_id}/workspaces |
Create a workspace |
GET |
/organizations/{org_id}/billing |
Get billing summary |
GET |
/organizations/{org_id}/billing/usage |
Get detailed usage breakdown |
GET |
/organizations/{org_id}/api-keys |
List API keys |
POST |
/organizations/{org_id}/api-keys |
Create an API key |
DELETE |
/organizations/{org_id}/api-keys/{key_id} |
Revoke an API key |
Authentication
| Method |
Path |
Description |
POST |
/auth/login |
Login with email and password |
POST |
/auth/refresh |
Refresh an access token |
POST |
/auth/logout |
Invalidate tokens |
GET |
/auth/whoami |
Get authenticated user info |
POST |
/orgs/{org_id}/workspaces/{workspace_id}/hosted-services/{service_id}/service-tokens/mint |
Mint an HSL service token |
POST |
/auth/sso/initiate |
Start SSO login flow |
Common Query Parameters
These parameters are accepted by most list endpoints:
| Parameter |
Type |
Description |
limit |
integer |
Maximum number of results (default: 25, max: 100) |
offset |
integer |
Number of results to skip |
sort |
string |
Field to sort by (e.g., created_at, name) |
order |
string |
Sort direction: asc or desc (default: desc) |
search |
string |
Full-text search across name and description |
status |
string |
Filter by status (e.g., active, draft, archived) |
Next Steps