Skip to main content

Connector Versions

Manage connector version history.

List Versions​

GET /api/connectors/{id}/versions

Authorization​

  • Authenticated user: Required (any authenticated session).

Versions are all connector rows sharing the same platform_name, including soft-deleted ones. is_active is true for the single non-deleted row. current_version_id is that active version's id.

Response​

{
  "platform_name": "Slack",
  "current_version_id": "ver_003",
  "versions": [
    {
      "id": "ver_003",
      "version": "1.2.0",
      "status": "production",
      "is_active": true,
      "restored_from": null,
      "created_at": "2024-01-15T00:00:00Z",
      "created_by": {
        "id": "analyst_001",
        "full_name": "John Doe"
      },
      "endpoint_count": 15,
      "enabled_endpoint_count": 15,
      "commit_message": "Add files.list endpoint"
    },
    {
      "id": "ver_002",
      "version": "1.1.0",
      "status": "production",
      "is_active": false,
      "restored_from": null,
      "created_at": "2024-01-08T00:00:00Z",
      "created_by": {
        "id": "analyst_001",
        "full_name": "John Doe"
      },
      "endpoint_count": 12,
      "enabled_endpoint_count": 10,
      "commit_message": null
    }
  ]
}

Example Request​

curl -X GET "https://api.traces.io/api/connectors/conn_slack001/versions" \
  -H "Authorization: Bearer <token>"

Activate Version​

POST /api/connectors/{id}/activate

Restore a (typically soft-deleted) version. The {id} in the path is the version to activate. To preserve forensic integrity this does not un-delete the row — it creates a new version copied from {id} (with restored_from set), soft-deleting whatever was previously active. The new version is numbered (highest major across the family) + 1 . 0 . 0.

Authorization​

  • Analyst / Admin: Required.

Request Body​

None. (The version to restore is identified by the path {id}.)

Response​

{
  "id": "conn_slack004",
  "message": "Version 1.1.0 restored as 4.0.0",
  "version": "4.0.0",
  "activated_from_version": "1.1.0"
}

Error Responses​

400 Bad Request - The target version is already the active one:

{
  "error": {
    "code": "ALREADY_ACTIVE",
    "message": "This version is already active"
  }
}

409 Conflict - Active collections exist in the family:

{
  "error": {
    "code": "ACTIVE_COLLECTIONS",
    "message": "Cannot change active version: 2 collection(s) are currently active"
  }
}

Check Active Collections​

GET /api/connectors/{id}/active-collections

Check if the connector has any active collections.

Response​

"Active" means status is one of pending, validating_creds, queued, or in_progress, across all versions in the connector family.

{
  "has_active_collections": true,
  "active_collection_count": 2,
  "active_collections": [
    {
      "id": "col_abc123",
      "case_reference": "CASE-2024-001",
      "status": "in_progress",
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "col_def456",
      "case_reference": null,
      "status": "pending",
      "created_at": "2024-01-15T11:00:00Z"
    }
  ]
}

Example Request​

curl -X GET "https://api.traces.io/api/connectors/conn_slack001/active-collections" \
  -H "Authorization: Bearer <token>"