Test Endpoints

Test connector authentication and individual endpoints.

Test Authentication

POST /api/connectors/{id}/test-auth

Test authentication configuration with provided credentials.

Authorization

• Analyst / Admin: Required.

note

The connector must be in testing status and have a platform_url, or the request returns 400. The test fires the first enabled endpoint using the supplied credentials.

Request Body

Field	Type	Required	Description
credential_type	string	Yes	One of oauth2, api_key, bearer, basic, query_params, token_exchange
credentials	object	Yes	Credential values; shape depends on credential_type

The credentials object accepts (by type): api_key + header_name (api_key); token (bearer); access_token + refresh_token (oauth2); username + password (basic); query_params: [{key, value}] (query_params); token_exchange_config (token_exchange).

Request Example

{
  "credential_type": "bearer",
  "credentials": {
    "token": "xoxb-123456789-abcdefghij"
  }
}

Response

{
  "success": true,
  "status_code": 200,
  "response_time_ms": 234,
  "response_preview": "{\"ok\":true, ... }"
}

Failed Authentication Response

{
  "success": false,
  "status_code": 401,
  "response_time_ms": 180,
  "error": "Authentication failed: 401 Unauthorized",
  "response_preview": "{\"ok\":false,\"error\":\"invalid_auth\"}"
}

Example Request

curl -X POST "https://api.traces.io/api/connectors/conn_slack001/test-auth" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_type": "bearer",
    "credentials": { "token": "xoxb-123456789-abcdefghij" }
  }'

---

Test Single Endpoint

POST /api/connectors/{id}/endpoints/{endpointId}/test

Test a specific endpoint. Credentials are not sent in the body — the request uses the connector's stored test credentials (selected via credential_slot_id). The body carries parameter values, pagination, body/recursion/iteration config, etc.

Request Body

All fields optional. Common fields:

Field	Type	Description
parameter_values	object (string→string)	Path parameter values substituted into {placeholders}
query_parameter_values	object (string→string)	Query string values
custom_headers	object (string→string)	Extra/override headers
body_params	object	{ type: "json"|"form-data"|"urlencoded"|"raw", content: string }
pagination_config	object	Pagination config (see Pagination reference)
max_pages	number (1–10)	Cap pages collected
full_collection	boolean	Collect all pages (sample history)
iteration_params	object	Iterate a parameter over multiple values (simple or paired)
recursion_config	object	Tree-traversal recursion config
response_transformations	array	Transforms applied before variable extraction
runtime_parameter_values	object (string→string)	Values for {{param}} templates
credential_slot_id	string	Which stored test-credential slot to use
endpoint_config	object	Inline endpoint definition for testing unpublished endpoints

Request Example

{
  "query_parameter_values": { "limit": "10", "types": "public_channel" },
  "max_pages": 2,
  "credential_slot_id": "slot_abc123"
}

Response

Returns a TestEndpointResponse (or an iteration summary when iteration_params is supplied). Representative shape:

{
  "success": true,
  "statusCode": 200,
  "responseTimeMs": 234,
  "data": { "ok": true, "channels": [ { "id": "C0123ABC", "name": "general" } ] }
}

Example Request

curl -X POST "https://api.traces.io/api/connectors/conn_slack001/endpoints/ep_conv_list/test" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query_parameter_values": { "limit": "5" },
    "credential_slot_id": "slot_abc123"
  }'

note

A streaming variant exists at POST /api/connectors/{id}/endpoints/{endpointId}/test/stream (Server-Sent Events) for long, paginated test runs.

---

Update Headers

PATCH /api/connectors/{id}/headers

Update the connector's default headers (stored on auth_config.defaultHeaders). Version-creating: like the publish flow, this creates a new connector version (new UUID, patch bump) and soft-deletes the source, migrating test data/credentials.

Authorization

• Analyst / Admin: Required.

Request Body

Field	Type	Required	Description
headers	object (string→string)	Yes	Replacement header map (replaces, not merges, so keys can be deleted)
authType	string	No	Auth type override (api_key/bearer/oauth2/basic/query_params/token_exchange)
expectedUpdatedAt	string	No	ISO timestamp of the version the client last saw. When supplied, enables optimistic concurrency (a stale write returns 409 VERSION_CONFLICT)

Request Example

{
  "headers": {
    "Accept": "application/json",
    "X-Custom-Header": "value"
  },
  "expectedUpdatedAt": "2024-01-15T10:30:00.000Z"
}

Response

The id is the new version's UUID.

{
  "id": "conn_slack002",
  "message": "Headers updated - new version 1.2.1 created",
  "version": "1.2.1",
  "previous_version": "1.2.0",
  "previous_id": "conn_slack001",
  "headers": {
    "Accept": "application/json",
    "X-Custom-Header": "value"
  },
  "updated_at": "2024-01-15T11:00:00.000Z"
}

Error Responses

409 Conflict — concurrent write or stale expectedUpdatedAt (flat shape):

{
  "error": "CONFLICT",
  "code": "VERSION_CONFLICT",
  "message": "This connector was modified by another analyst. Reload to get the latest version."
}

---

Get Headers

GET /api/connectors/{id}/headers

Returns the connector's default headers and auth type.

Response

{
  "headers": { "Accept": "application/json" },
  "authType": "bearer"
}