API Reference

Managed Wayfinder API

Use the managed Wayfinder endpoints to route prompts, capture feedback, and improve model selection over time. This reference documents the public endpoints available in the hosted service.

Authentication

Pass your Wayfinder token in the request header.

X-Wayfinder-Token: wf_...

POST /api/users/register

Public

Create a user account and receive your first Wayfinder token. User self-service must be enabled on the hosted service.

Request body

email (string, required)
password (string, required)

{
  "email": "[email protected]",
  "password": "your-secure-password"
}

Response body

{
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "tier": "free",
    "status": "active",
    "created_at": "2026-01-15T18:00:00.000Z",
    "updated_at": "2026-01-15T18:00:00.000Z",
    "last_login_at": null
  },
  "token": {
    "id": "token_123",
    "token": "wf_...",
    "name": "Default Token",
    "is_primary": true
  }
}

POST /api/users/login

Public

Authenticate a user and return account details plus existing tokens. Token values are not returned for security.

Request body

{
  "email": "[email protected]",
  "password": "your-secure-password"
}

Response body

{
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "tier": "free",
    "status": "active",
    "created_at": "2026-01-15T18:00:00.000Z",
    "updated_at": "2026-01-15T18:00:00.000Z",
    "last_login_at": "2026-01-15T18:10:00.000Z"
  },
  "tokens": [
    {
      "id": "token_123",
      "name": "Default Token",
      "is_primary": true,
      "environment": "dev",
      "created_at": "2026-01-15T18:00:00.000Z",
      "updated_at": "2026-01-15T18:00:00.000Z"
    }
  ]
}

POST /route

Routing

Route a prompt through Wayfinder to receive a primary and alternate model recommendation.

Request body

prompt (string, required)
context (object, optional)
prefer_model (string, optional)
metadata (object, optional)
router_model (openai | gemini | consensus, optional)

{
  "prompt": "Summarize this support ticket: user cannot reset password on iOS",
  "metadata": { "channel": "support" },
  "router_model": "consensus"
}

Response body

{
  "primary": { "model": "gpt-4-turbo", "score": 9, "reason": "Best suited for this task based on prompt analysis" },
  "alternate": { "model": "gpt-4o", "score": 8, "reason": "Viable alternative with different strengths" },
  "request_id": "6f57f863-01f6-4c1f-a2d0-5385af4a0605",
  "router_model_used": "consensus",
  "from_cache": false
}

POST /feedback

Feedback

Submit feedback for a considered response to improve future routing.

Request body

request_id (string, required)
selected_model (string, required)
intent_label (code_review | coding | legal | summarization | reasoning | creative | support | other, required)
rating (positive | negative | neutral, optional)
preferred_model (string, optional)
metadata (object, optional)

{
  "request_id": "6f57f863-01f6-4c1f-a2d0-5385af4a0605",
  "selected_model": "gpt-4-turbo",
  "intent_label": "support",
  "rating": "positive",
  "metadata": { "ticket_id": "SUP-1842" }
}

Response body

{
  "feedback_id": "6391cb03-1a23-4727-ab90-675766635182",
  "acknowledged": true,
  "knowledge_updated": true
}

Token Management

Auth required

Manage tokens for your account. Provide X-Wayfinder-Tokenfrom an existing token to authorize these endpoints.

GET /api/tokens

List tokens for the authenticated user.

POST /api/tokens

Create a new token for the authenticated user.

DELETE /api/tokens/:id

Delete a non-primary token.

POST /api/tokens/:id/rotate

Rotate a token and receive a new token value.

Create token request body

name (string, optional)
eligible_models (string[], optional)
environment (prod | dev, optional)
router_model_preference (openai | gemini | consensus, optional)

If eligible_models is omitted or empty, the backend resolves model eligibility from the current default-token profile.

{
  "name": "Staging Token",
  "eligible_models": ["gpt-4o-mini", "gemini-2.5-flash"],
  "environment": "dev",
  "router_model_preference": "consensus"
}

Rotate token response body

{
  "token": "wf_...",
  "rotated_at": "2026-01-15T18:20:00.000Z"
}

Admin default-token profile

Admins can manage the system-wide default token model list via GET/PUT /admin/default-token-profile.

{
  "profile": {
    "model_ids": ["gpt-4o-mini", "gemini-2.5-flash"],
    "version": 4
  },
  "effective_model_ids": ["gpt-4o-mini", "gemini-2.5-flash"],
  "missing_model_ids": [],
  "recommended_model_ids": ["gpt-4o-mini", "gemini-2.5-flash"],
  "cache_scope": "global:v4",
  "cache_flush_recommended": true,
  "cache_flush_hint": "Clear global cache if immediate cleanup is needed."
}

Errors

Errors are returned in a standard JSON shape.

{
  "error": "ValidationError",
  "message": "Invalid request body",
  "details": { "...": "..." },
  "timestamp": "2026-01-15T18:55:47.288Z"
}