AimableDocs
DocsAPI Reference

Tools Space

Tools-Space API

The tools-space domain in the Aimable Platform API (v0.1.0) enables developers to interact with tools associated with a specific space—a logical container for organizing resources, users, and functionality. This API allows you to list available tools within a space and execute them dynamically by passing arguments. It's ideal for building automation workflows, integrations, or UIs that need to trigger space-specific actions like data exports, report generation, or system syncs.

Key Concepts

  • Space: A scoped environment identified by a unique space_id (UUID). Tools are bound to a space and inherit its context and permissions.
  • Tool: A predefined function or action (e.g., export_data, sync_users) that can be executed within a space. Each tool has a tool_name and accepts structured arguments.
  • Execution: Tools are invoked via POST requests with a JSON payload containing input parameters. The response depends on the tool’s implementation.

Authentication is required for all operations using a Bearer token in the Authorization header. Some endpoints may also accept an optional X-API-Key header for legacy or service-level access.

List Available Tools in a Space

Use this endpoint to discover which tools are available in a given space.

Request

curl -X GET 'https://api.aimable.com/api-proxy/v1/spaces/550e8400-e29b-41d4-a716-446655440000/tools' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'X-API-Key: optional-key-if-required'

Response (200 OK)

[
  {
    "tool_name": "export_data",
    "description": "Export space data in CSV or JSON format",
    "arguments_schema": {
      "format": { "type": "string", "enum": ["csv", "json"] },
      "include_metadata": { "type": "boolean" }
    }
  },
  {
    "tool_name": "sync_users",
    "description": "Sync user list with external identity provider",
    "arguments_schema": {
      "provider": { "type": "string" },
      "force_update": { "type": "boolean" }
    }
  }
]

Execute a Tool in a Space

Run a specific tool by name and pass required arguments in the request body.

Request

curl -X POST 'https://api.aimable.com/api-proxy/v1/spaces/550e8400-e29b-41d4-a716-446655440000/tools/export_data/execute' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "arguments": {
      "format": "csv",
      "include_metadata": true
    }
  }'

Response (200 OK)

{
  "result": "success",
  "output_url": "https://data.aimable.com/downloads/export-abc123.csv",
  "message": "Data export completed successfully."
}

⚠️ If the request is malformed or validation fails, a 422 error is returned:

{
  "detail": [
    {
      "loc": ["body", "arguments", "format"],
      "msg": "Input should be 'csv' or 'json'",
      "type": "value_error.enum",
      "input": "xml"
    }
  ]
}

Common Workflow: Export and Sync Data

Here’s a typical sequence a developer might use:

  1. List tools to confirm export_data and sync_users are available.
  2. Execute sync_users before export to ensure data is up to date:
curl -X POST '/api-proxy/v1/spaces/550e8400-e29b-41d4-a716-446655440000/tools/sync_users/execute' \
  -H 'Authorization: Bearer <token>' \
  -d '{"arguments": {"provider": "okta", "force_update": false}}'
  1. Once sync completes, trigger export_data:
curl -X POST '/api-proxy/v1/spaces/550e8400-e29b-41d4-a716-446655440000/tools/export_data/execute' \
  -H 'Authorization: Bearer <token>' \
  -d '{"arguments": {"format": "json", "include_metadata": true}}'
  1. Process the returned output_url to download or forward the exported data.

Authentication & Error Handling

All endpoints require authentication. Use a Bearer token:

Authorization: Bearer <your-token>

Optional: Include X-API-Key if your integration relies on API key-based access.

Common Errors

| Status | Meaning | |-------|--------| | 401 Unauthorized | Missing or invalid access token | | 403 Forbidden | User lacks permission to access the space or tool | | 422 Unprocessable Entity | Invalid input; check detail for field-specific errors |

Always validate input against the tool's expected schema (retrieved via the GET /tools endpoint) to avoid 422 errors.

By combining discovery and execution, the tools-space API gives you dynamic control over space-level operations—making it easy to automate, integrate, and extend functionality across your Aimable Platform spaces.

Related Endpoints