Tool Execution

Execute Syncello tools via HTTP POST requests. Each tool has its own endpoint and accepts specific parameters.

Endpoint Format

POST /v1/tools/{platform}/{toolName}

Where:

{platform} is one of: tape, podio, sharefile, or web
{toolName} is the specific tool name (e.g., listApps, createRecord)

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication
`Content-Type`	Yes	Must be `application/json`

Example: List Tape Apps

Request

cURL

curl -X POST https://api.syncello.io/v1/tools/tape/listApps \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": 12345
  }'

Response

Success Response

{
  "success": true,
  "data": {
    "apps": [
      {
        "id": 1001,
        "name": "Contacts",
        "description": "Customer contacts database"
      },
      {
        "id": 1002,
        "name": "Projects",
        "description": "Project tracking"
      }
    ]
  }
}

Example: Create a Record

Request

cURL

curl -X POST https://api.syncello.io/v1/tools/tape/createRecord \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": 1001,
    "fields": {
      "Name": "John Smith",
      "Email": "[email protected]",
      "Company": "Acme Inc"
    }
  }'

Response

Success Response

{
  "success": true,
  "data": {
    "record_id": 98765,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Response Formats

Text Response (Default)

By default, responses are optimized for AI consumption with human-readable text:

{
  "success": true,
  "data": "Found 2 apps in workspace 12345:\n1. Contacts (ID: 1001)\n2. Projects (ID: 1002)"
}

JSON Response

Add ?format=json to get structured data:

curl -X POST "https://api.syncello.io/v1/tools/tape/listApps?format=json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": 12345}'

Base64 Response

Add ?base64=true for base64-encoded responses (useful for binary data or when avoiding JSON escaping issues):

curl -X POST "https://api.syncello.io/v1/tools/tape/listApps?base64=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": 12345}'

Error Handling

Errors return appropriate HTTP status codes with details:

400 Bad Request

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "workspace_id is required",
    "details": {
      "parameter": "workspace_id",
      "expected": "number"
    }
  }
}

Common Error Codes

HTTP Status	Code	Description
400	`INVALID_PARAMETER`	Missing or invalid request parameter
401	`UNAUTHORIZED`	Missing or invalid authentication
403	`FORBIDDEN`	Token lacks required permissions
404	`NOT_FOUND`	Tool or resource not found
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error

Next Steps

Browse the Tools Reference to see all available tools and their parameters.