Discover Endpoint Docs

Best-effort discovery of the vendor documentation URL for a single endpoint. The handler infers a likely docs page from the endpoint's method, path, platform name, and platform URL.

POST /api/connectors/{id}/endpoints/{endpointId}/discover-docs

note

This is best-effort and non-persisting. On failure it returns { "url": null, "note": "..." } with a 200 rather than a 500, so the UI never breaks. The discovered URL is not saved server-side — the client stores it through the normal endpoint edit/save flow.

Authorization

• Analyst (or admin): Required. Unauthenticated requests receive 401; users without the role receive 403.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Connector ID
endpointId	string	Yes	Endpoint ID (must exist in the connector)

Request Body

None.

Response

{
  "url": "https://api.slack.com/methods/conversations.list",
  "note": null
}

Field	Type	Description
url	string | null	The discovered documentation URL, or null if none could be found
note	string | null	An optional explanatory note (e.g. why discovery returned no URL or what failed)

Example Request

curl -X POST "https://api.traces.io/api/connectors/conn_slack001/endpoints/ep_conv_list/discover-docs" \
  -H "Authorization: Bearer <token>"

Error Responses

401 Unauthorized

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

403 Forbidden

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

404 Not Found

The connector or the endpoint within it was not found:

{ "error": { "code": "NOT_FOUND", "message": "Endpoint not found in connector" } }

tip

Discovery failures are not surfaced as 500s. If the underlying lookup throws, the response is still 200 with { "url": null, "note": "<message>" }.