Examine Endpoint (AI)

Analyse one endpoint's response body with an AI model to find fields that are good candidates to feed parameters of other endpoints in the same connector — i.e. suggested dependency mappings. The response is streamed as plain text with interleaved progress lines.

POST /api/connectors/{id}/examine-endpoint

note

This endpoint only suggests mappings — it does not persist anything. The analyst reviews the recommendations and applies the ones they want through the normal save flow.

Authorization

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

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Connector ID

Request Body

Field	Type	Required	Description
endpointId	string	Yes	ID of the endpoint whose response is being examined (the "source")
responseData	any	Yes	The response body returned by a test run of that endpoint. Large samples are truncated before being sent to the model
executionOrder	string[]	No	Ordered endpoint IDs, used to judge which downstream endpoints could consume a field
existingMappings	array	No	Already-configured mappings (sourceEndpointId, targetEndpointId, targetParameter) so they are not re-suggested
existingVariableNames	string[]	No	Names of variables the analyst already defined, so they are not re-suggested

{
  "endpointId": "ep_accounts",
  "responseData": { "data": [{ "account_id": "A1", "name": "Acme" }] },
  "executionOrder": ["ep_token", "ep_accounts", "ep_users"],
  "existingMappings": [],
  "existingVariableNames": []
}

Response

A streaming text/plain body (Content-Type: text/plain; charset=utf-8). Two kinds of content arrive over the stream:

1. Progress lines — single lines beginning with the literal token PROGRESS: describing what the model is doing (e.g. PROGRESS: Reading the response from GET /accounts). Display only.
2. Final result — after generation completes, a single JSON sentinel line is appended (prefixed by \n):

{
  "__result": {
    "recommendations": [
      {
        "sourceJsonPath": "data[*].account_id",
        "fieldLabel": "account_id",
        "targetEndpointId": "ep_users",
        "targetEndpointLabel": "GET /accounts/{accountId}/users",
        "suggestedParameter": "accountId",
        "parameterLocation": "path",
        "justification": "Account IDs from the accounts list fill the {accountId} path param."
      }
    ],
    "model": "claude-sonnet-4-6"
  }
}

Field	Description
sourceJsonPath	JSONPath into the source endpoint's response
fieldLabel	Human-friendly label for the field
targetEndpointId	The consuming endpoint's ID
targetEndpointLabel	Friendly name, or METHOD path, of the consumer
suggestedParameter	The parameter name to populate on the consumer
parameterLocation	"path" or "query"
justification	One or two sentences explaining the suggestion
model	The AI model that produced the recommendations

recommendations may be an empty array when nothing is a good fit.

Stream error sentinel

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

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

Error Responses

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

400 Bad Request

{ "error": { "code": "BAD_REQUEST", "message": "No response data to examine. Run a test first." } }

endpointId missing yields { "code": "BAD_REQUEST", "message": "endpointId is required" }.

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": "Endpoint not found in connector" } }

500 Internal Server Error

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