Create Connector

Create a new connector for a platform.

POST /api/connectors

Authorization

• Analyst: Required

Request Body

Field	Type	Required	Description
platform_name	string	Yes	Name of the platform (e.g., "Slack")
platform_url	string	No	Base URL of the platform API
version	string	Yes	Semantic version (e.g., "1.0.0")
endpoints	array	Yes	Array of endpoint configurations
auth_config	object	Yes	Authentication configuration
rate_limit_global	object	No	Global rate limit settings
default_data_extraction	object	No	Fallback data-extraction config
runtime_parameters	array	No	Runtime parameter definitions
documentation_url	string	No	Link to platform documentation
status	string	No	Initial status: testing or production (default: testing)

Endpoint Configuration

{
  path: string,           // API path, e.g., "/api/users.list"
  method: string,         // HTTP method: "GET", "POST", etc.
  order: number,          // Execution order (lower = first)
  dependencies: string[], // Endpoint IDs that must run first
  rate_limit: {
    requests: number,
    window_seconds: number
  },
  pagination?: {
    type: 'cursor' | 'offset' | 'page',
    params: object
  },
  data_extraction: {
    path: string,         // JSONPath to data array
    file_naming: string   // Naming template
  }
}

Auth Configuration

{
  type: 'oauth2' | 'api_key' | 'bearer' | 'basic' | 'certificate' | 'query_params' | 'token_exchange',
  required_scopes?: string[],
  token_endpoint?: string,
  refresh_supported?: boolean
}

Request Example

{
  "platform_name": "Slack",
  "platform_url": "https://slack.com/api",
  "version": "1.0.0",
  "endpoints": [
    {
      "path": "/conversations.list",
      "method": "GET",
      "order": 1,
      "dependencies": [],
      "rate_limit": {
        "requests": 50,
        "window_seconds": 60
      },
      "pagination": {
        "type": "cursor",
        "params": {
          "cursor_param": "cursor",
          "cursor_path": "$.response_metadata.next_cursor"
        }
      },
      "data_extraction": {
        "path": "$.channels[*]",
        "file_naming": "channel_{id}.json"
      }
    },
    {
      "path": "/conversations.history",
      "method": "GET",
      "order": 2,
      "dependencies": ["conversations.list"],
      "rate_limit": {
        "requests": 50,
        "window_seconds": 60
      },
      "pagination": {
        "type": "cursor",
        "params": {
          "cursor_param": "cursor",
          "cursor_path": "$.response_metadata.next_cursor"
        }
      },
      "data_extraction": {
        "path": "$.messages[*]",
        "file_naming": "channel_{channel}_messages.json"
      }
    }
  ],
  "auth_config": {
    "type": "oauth2",
    "required_scopes": ["channels:read", "channels:history"],
    "token_endpoint": "https://slack.com/api/oauth.v2.access",
    "refresh_supported": true
  },
  "rate_limit_global": {
    "requests": 100,
    "window_seconds": 60
  },
  "documentation_url": "https://api.slack.com/docs"
}

Response

Returns 201 Created:

{
  "id": "conn_slack001",
  "message": "Connector created successfully"
}

Example Request

curl -X POST "https://api.traces.io/api/connectors" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_name": "Slack",
    "version": "1.0.0",
    "endpoints": [...],
    "auth_config": {
      "type": "oauth2",
      "required_scopes": ["channels:read"]
    }
  }'

Error Responses

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "endpoints array cannot be empty"
  }
}

note

This endpoint does not enforce duplicate detection — multiple connectors may share a platform name (versioning is handled by the publish flow on PATCH /api/connectors/{id}).