Connector Phases

Execution phases group a connector's endpoints into ordered, human-readable domains (and sub-groups called stages). They drive the order in which endpoints run during a collection and give analysts a two-level mental model of the connector.

Phases are stored separately from the connector's forensic content, so editing them mutates in place — it does not create a new connector version.

Authorization

• GET: any authenticated user. Unauthenticated requests receive 401.
• POST / PUT / PATCH / DELETE: Analyst or admin with an analyst profile. Unauthenticated or unauthorized callers receive 401.

Phase Object

Field	Type	Description
id	string	Phase ID
name	string	Display name (e.g. "Users & Groups")
position	number	Zero-based order within the connector
stages	array/object	Stage definitions (each stage names a sub-group and its endpoint IDs)
connectorId	string	Owning connector ID

All mutating endpoints return the full, position-ordered phase list after applying the change.

---

List Phases

GET /api/connectors/{id}/phases

Returns all phases for the connector, ordered by position ascending.

Response

{
  "phases": [
    {
      "id": "phase_001",
      "name": "Account & Authentication",
      "position": 0,
      "stages": [
        { "name": "Authentication", "endpointIds": ["ep_token"] },
        { "name": "Account Discovery", "endpointIds": ["ep_accounts"] }
      ],
      "connectorId": "conn_slack001"
    }
  ]
}

---

Create Phase

POST /api/connectors/{id}/phases

Appends a new phase at the end (its position is max(position) + 1).

Request Body

Field	Type	Required	Description
name	string	No	Phase name. Defaults to "New Phase"
stages	array	No	Initial stages. Defaults to []

{ "name": "Reporting", "stages": [] }

Response

201 Created — returns the full phase list (see above).

---

Replace All Phases

PUT /api/connectors/{id}/phases

Bulk-replaces every phase for the connector in a single transaction: all existing phases are deleted and the supplied phases are re-inserted in array order (position is assigned by index). Useful for drag-to-reorder UIs.

Request Body

Field	Type	Required	Description
phases	array	No	Ordered list of phases. Defaults to [] (clears all phases)
phases[].name	string	Yes	Phase name
phases[].stages	array	No	Stages for this phase (defaults to [])

{
  "phases": [
    { "name": "Account & Authentication", "stages": [ ... ] },
    { "name": "Users & Groups", "stages": [ ... ] }
  ]
}

Response

Returns the full, re-numbered phase list.

---

Update a Phase

PATCH /api/connectors/{id}/phases/{phaseId}

Renames a phase and/or updates its stages. Only the fields you send are changed.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Connector ID
phaseId	string	Yes	Phase ID (must belong to the connector)

Request Body

Field	Type	Required	Description
name	string	No	New phase name
stages	array	No	Replacement stages

{ "name": "Authentication & Tenancy" }

Response

Returns the full phase list.

---

Delete a Phase

DELETE /api/connectors/{id}/phases/{phaseId}

Deletes the phase and re-numbers the remaining phases so positions stay contiguous (0, 1, 2, …).

Response

Returns the full, re-numbered phase list.

---

Error Responses

401 Unauthorized

{ "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } }

404 Not Found

The connector does not exist (or the phase does not belong to it):

{ "error": { "code": "NOT_FOUND", "message": "Phase not found" } }

500 Internal Server Error

{ "error": { "code": "INTERNAL_ERROR", "message": "An error occurred" } }