Skip to main content

Reorder Endpoints (AI)

Ask an AI model to reorder a connector's endpoints into the most logical execution sequence and organise them into a two-level phase/stage hierarchy. The response is streamed as plain text so the UI can show the model's output in real time.

POST /api/connectors/{id}/reorder-endpoints

note

This endpoint only computes a suggested order — it does not persist anything. The client applies the result through the normal endpoint/phase save flow.

Authorization​

  • Analyst (or admin) with an analyst profile. Unauthenticated requests receive 401; users without the role/profile receive 403.

Path Parameters​

ParameterTypeRequiredDescription
idstringYesConnector ID

Request Body​

None. The handler reads the connector's endpoints and any saved dependency mappings from the database; analyst-configured dependency mappings are passed to the model as hard ordering constraints that must not be violated.

Response​

The handler returns a streaming text/plain body (Content-Type: text/plain; charset=utf-8), not JSON. Consume it as a stream:

  1. Live tokens — the model's raw output streams through as it is generated. This is intended for display only.
  2. Final result — once the stream completes, a single JSON sentinel line is appended, separated by a blank line, prefixed by \n\n:
{
  "__result": {
    "orderedIds": ["ep_token", "ep_accounts", "ep_users", "ep_user_detail"],
    "phases": [
      {
        "name": "Account & Authentication",
        "stages": [
          { "name": "Authentication", "endpointIds": ["ep_token"] },
          { "name": "Account Discovery", "endpointIds": ["ep_accounts"] }
        ]
      }
    ],
    "reasoning": "Auth first, then account discovery, then user listing and detail."
  }
}
  • orderedIds — the full flat list of endpoint IDs in execution order. Any endpoint the model omitted is appended at the end so the list always covers every endpoint.
  • phases — the two-level grouping (each stage's endpoints map back to real endpoint IDs).
  • reasoning — a one-line rationale.

If the connector has no endpoints, the handler returns JSON directly (not a stream): { "phases": [], "reasoning": "No endpoints to reorder." }.

Stream error sentinel​

If generation fails mid-stream, an error sentinel is appended instead:

{ "__error": "Non-JSON response: ..." }

Error Responses​

Setup errors (before streaming begins) are returned as JSON with the matching HTTP status:

401 Unauthorized​

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

403 Forbidden​

{ "error": { "code": "FORBIDDEN", "message": "Analyst role required" } }

404 Not Found​

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

500 Internal Server Error​

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