AimableDocs
DocsAPI Reference
POST/v1/spaces/{space_id}/skills/{slug}/executions

Start Standalone Execution Route

Path Parameters

NameTypeRequiredDescription
space_idstring (uuid)Required
slugstringRequired

Headers

NameTypeRequiredDescription
Idempotency-KeystringOptional
X-API-KeystringOptional

Request Body

application/jsonRequired
inputsobjectRequiredValidated against the skill version's manifest inputs schema.
file_source_idsstring[]Filenames (relative to the caller's personal collection) to stage into the skill workspace's `inputs/materials/` directory before execution. Same semantics as chat's `uploaded_files` field — files must have been uploaded previously via `POST /v1/files/`. Missing files are skipped.
modelobjectOptional tenant_model alias to run this skill against. When set, overrides the space's default model for this execution only. The alias must be in the space's allow-list. If unset (typical for automation / scheduled runs) the pipeline uses the space's default model.

Request

curl -X POST '/api-proxy/v1/spaces/{space_id}/skills/{slug}/executions' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": {},
  "file_source_ids": [
    "string"
  ],
  "model": {}
}'

Response

201(generated)
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "space_id": "550e8400-e29b-41d4-a716-446655440000",
    "principal_id": "550e8400-e29b-41d4-a716-446655440000",
    "skill_slug": "string",
    "skill_version": {},
    "source": "standalone",
    "state": "queued",
    "parent_execution_id": {},
    "created_at": "2024-01-01T00:00:00Z",
    "started_at": {},
    "finished_at": {},
    "failure_reason": {},
    "resource_usage": {
      "input_tokens": 0,
      "output_tokens": 0,
      "cost_usd": "string",
      "wallclock_ms": {},
      "iteration_count": 0
    },
    "inputs": {},
    "outputs": {},
    "error": {},
    "artifacts": [
      {
        "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
        "relpath_in_workspace": {},
        "document_type": {},
        "download_url": "string",
        "size_bytes": {}
      }
    ],
    "sub_executions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
        "space_id": "550e8400-e29b-41d4-a716-446655440000",
        "principal_id": "550e8400-e29b-41d4-a716-446655440000",
        "skill_slug": "string",
        "skill_version": {},
        "source": "standalone",
        "state": "queued",
        "parent_execution_id": {},
        "created_at": "2024-01-01T00:00:00Z",
        "started_at": {},
        "finished_at": {},
        "failure_reason": {},
        "resource_usage": {
          "input_tokens": 0,
          "output_tokens": 0,
          "cost_usd": "string",
          "wallclock_ms": {},
          "iteration_count": 0
        }
      }
    ],
    "chat_thread_id": {},
    "chat_message_id": {},
    "chat_tool_call_id": {},
    "workspace_archive_id": {},
    "langfuse_trace_id": {},
    "idempotency_key": {}
  }
}

Error Responses