Files
Molly Fraser 4bccdc4ed6 feat: show and filter by organization in AI Gateway sessions API (#32057)
Adds an `organization` filter to `GET /api/v2/ai-gateway/sessions` (and
its `/api/v2/aibridge/sessions` alias) and returns the organization an
interception was attributed to, and how it was chosen, on sessions,
threads and agentic actions, as proposed in the surface definitions on
AIGOV-754. No migration: `aibridge_interceptions.organization_id` and
`organization_source` already exist (000634).

The filter accepts an organization name or ID and keeps sessions with at
least one interception in that organization; the count uses the same
rule so pagination totals match. Each session, on the list and detail
responses, lists the organizations its interceptions were attributed to,
ordered by name, with the distinct sources used for each, or `[]` when
none was stored. Each thread carries the organization of its root
interception and each agentic action carries its own, or null when none
was stored. The new filter is listed in the AI Gateway monitoring docs.

Refs AIGOV-754

## Open questions for reviewers

- **Multi-org sessions** (AIGOV-776): the filter is row-level, like
provider and model. A session spanning two orgs is listed under each
org's filter, and with the filter on, `threads`, `started_at` and
`ended_at` only cover the matching interceptions, while providers,
models, tokens and `organizations` cover the whole session. Is that the
desired behavior?
- **Unknown org ID:** an unknown org name returns 400, but an unknown
org ID returns an empty page, because `parseOrganization` does not look
up UUIDs. This matches workspaces and templates, but the spec says 400.

## Notes for reviewers
- `aiBridgeSessionOrganizations` returns an empty list if the
organizations JSON from the query can’t be decoded, rather than failing
the whole request. The field is supplementary, so a decoding problem
shouldn’t take down the sessions list, but it does mean a SQL bug here
would show up as empty data rather than an error. The alternative is to
log the error before returning the empty list.
- A thread’s organization is taken from its root interception only. If
later requests in the same thread were attributed to a different
organization, that shows on each agentic action’s own organization
field.

<details>
<summary>Implementation notes</summary>

- `coderd/database/queries/aibridge.sql`:
- `@organization_id` filter in `CountAIBridgeSessions` and the
`session_page` CTE of `ListAIBridgeSessions`.
- New `sorg` lateral in `ListAIBridgeSessions` that groups the session's
interceptions by organization, collects distinct sources, joins
`organizations` (deleted orgs still resolve) and returns a JSON array.
- `ListAIBridgeSessionThreads` resolves the organization name, display
name and icon through a `LEFT JOIN LATERAL` in the final `SELECT`. A
plain join on `organizations` is not safe there: the query has two
`@authorize_filter` placeholders, and the injected filter can reference
a bare `id`, which would be ambiguous next to `organizations.id`. The
lateral only exposes the three selected columns. This answers the
authorize-filter open question from the surface proposal.
- `coderd/database/modelqueries.go`: the hand-written
`ListAuthorizedAIBridgeSessions`, `CountAuthorizedAIBridgeSessions` and
`ListAuthorizedAIBridgeSessionThreads` gain the new argument and scan
columns. The compiler does not catch a mismatch here; it fails at
runtime.
- `enterprise/coderd/aibridge.go`: pass `OrganizationID` into
`CountAIBridgeSessionsParams`, which is built field by field, and list
the `organization` key in `@Param q`.
- `coderd/searchquery/search.go`: `organization` key via
`parseOrganization`.
- `codersdk/aibridge.go`: `AIBridgeInterceptionOrganizationSource` enum,
`AIBridgeInterceptionOrganization`, `AIBridgeSessionOrganization`, new
response fields and `AIBridgeListSessionsFilter.Organization`, per the
proposed Go definitions.
- `coderd/database/db2sdk/db2sdk.go`: decode the session organizations
JSON, never returning nil; `AIBridgeInterceptionOrganizationSource`
converter; build one organization per interception while grouping thread
rows, and use it for the thread (root interception) and each agentic
action.
- `site/`: add `organizations: []` to two frontend mocks, now that the
field is required in the generated types.
- `docs/ai-governance/ai-gateway/monitoring.md`: `organization` added to
the sessions API query filters.
- Tests: `TestAIBridgeSessions` (name and ID parsing),
`TestAIBridgeListSessions/Filters` (by name and ID, checks count and
page), `FilterErrors/UnknownOrganization`,
`TestAIBridgeListSessions/Organizations` (multi-org ordering and
sources, no-org session returns `[]`, filtering by either org returns
the multi-org session and never the no-org one),
`TestAIBridgeGetSessionThreads/Organizations` (thread uses the root's
org, each action its own, null when none, session `organizations` on the
detail endpoint), and `TestAIBridgeInterceptionOrganizationSource`
(every database source maps to an SDK value).
- Remaining files are generated by `make gen`.

</details>

---

Code written by @mollymaefraser, with Coder Agents used as a guide:
explaining the existing code path, reviewing each step, and running
tests.
2026-11-19 09:07:56 +00:00

14 KiB
Generated

title
title
AI Gateway

List AI Gateway clients

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/ai-gateway/clients \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/ai-gateway/clients

Alias: also available at /api/v2/aibridge/clients for backward compatibility.

Example responses

200 Response

[
  "string"
]

Responses

Status Meaning Description Schema
200 OK OK array of string

Response Schema

To perform this operation, you must be authenticated. Learn more.

List AI Gateway models

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/ai-gateway/models \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/ai-gateway/models

Alias: also available at /api/v2/aibridge/models for backward compatibility.

Parameters

Name In Type Required Description
q query string false Search query in the format key:value. Available keys are: model. A bare term searches by model. The match is a case-insensitive substring.
model query string false Literal model identifier substring, matched case-insensitively. Cannot be combined with q.

Example responses

200 Response

[
  "string"
]

Responses

Status Meaning Description Schema
200 OK OK array of string

Response Schema

To perform this operation, you must be authenticated. Learn more.

List AI Gateway providers

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/ai-gateway/providers \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/ai-gateway/providers

Example responses

200 Response

[
  {
    "display_name": "string",
    "icon": "string",
    "name": "string",
    "type": "openai"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.AIBridgeProvider

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» display_name string false
» icon string false
» name string false
» type codersdk.AIProviderType false

Enumerated Values

Property Value(s)
type anthropic, azure, bedrock, copilot, google, openai, openai-compat, openrouter, vercel

To perform this operation, you must be authenticated. Learn more.

List AI Gateway sessions

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/ai-gateway/sessions \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/ai-gateway/sessions

Alias: also available at /api/v2/aibridge/sessions for backward compatibility.

Parameters

Name In Type Required Description
q query string false Search query in the format key:value. Available keys are: initiator, provider, provider_name, model, client, session_id, organization, started_after, started_before.
limit query integer false Page limit
after_session_id query string false Cursor pagination after session ID (cannot be used with offset)
offset query integer false Offset pagination (cannot be used with after_session_id)

Example responses

200 Response

{
  "count": 0,
  "sessions": [
    {
      "client": "string",
      "ended_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "initiator": {
        "avatar_url": "http://example.com",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "username": "string"
      },
      "last_active_at": "2019-08-24T14:15:22Z",
      "last_prompt": "string",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "models": [
        "string"
      ],
      "network_calls": {
        "blocked": 0,
        "total": 0
      },
      "organizations": [
        {
          "display_name": "string",
          "icon": "string",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "sources": [
            "workspace"
          ]
        }
      ],
      "providers": [
        "string"
      ],
      "started_at": "2019-08-24T14:15:22Z",
      "threads": 0,
      "token_usage_summary": {
        "cache_read_input_tokens": 0,
        "cache_write_input_tokens": 0,
        "input_tokens": 0,
        "output_tokens": 0
      }
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.AIBridgeListSessionsResponse

To perform this operation, you must be authenticated. Learn more.

Get AI Gateway session threads

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/ai-gateway/sessions/{session_id} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/ai-gateway/sessions/{session_id}

Alias: also available at /api/v2/aibridge/sessions/{session_id} for backward compatibility.

Parameters

Name In Type Required Description
session_id path string true Session ID (client_session_id or interception UUID)
after_id query string false Thread pagination cursor (forward/older)
before_id query string false Thread pagination cursor (backward/newer)
limit query integer false Number of threads per page (default 50)

Example responses

200 Response

{
  "client": "string",
  "ended_at": "2019-08-24T14:15:22Z",
  "id": "string",
  "initiator": {
    "avatar_url": "http://example.com",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "username": "string"
  },
  "metadata": {
    "property1": null,
    "property2": null
  },
  "models": [
    "string"
  ],
  "network_call_logs": [
    {
      "allowed": true,
      "captured_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "detail": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "matched_rule": "string",
      "method": "string",
      "proto": "string",
      "sequence_number": 0,
      "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
    }
  ],
  "network_calls": {
    "blocked": 0,
    "total": 0
  },
  "network_domain_count": 0,
  "network_top_domains": [
    {
      "count": 0,
      "domain": "string"
    }
  ],
  "organizations": [
    {
      "display_name": "string",
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "sources": [
        "workspace"
      ]
    }
  ],
  "page_ended_at": "2019-08-24T14:15:22Z",
  "page_started_at": "2019-08-24T14:15:22Z",
  "providers": [
    "string"
  ],
  "started_at": "2019-08-24T14:15:22Z",
  "threads": [
    {
      "agent_firewall_sequence_number": 0,
      "agent_firewall_session_id": "3735294f-18b1-4e7a-a269-99c30f0b30e7",
      "agentic_actions": [
        {
          "attribution": {
            "property1": "string",
            "property2": "string"
          },
          "interception_id": "34d9b688-63ad-46f4-88b5-665c1e7f7824",
          "model": "string",
          "organization": {
            "display_name": "string",
            "icon": "string",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "name": "string",
            "source": "workspace"
          },
          "priced_model": {
            "cache_read_price": 0,
            "cache_write_price": 0,
            "input_price": 0,
            "model": "string",
            "output_price": 0
          },
          "thinking": [
            {
              "text": "string"
            }
          ],
          "token_usage": {
            "cache_read_input_tokens": 0,
            "cache_write_input_tokens": 0,
            "cost_micros": 0,
            "has_unpriced_usage": true,
            "input_tokens": 0,
            "metadata": {
              "property1": null,
              "property2": null
            },
            "output_tokens": 0
          },
          "tool_calls": [
            {
              "created_at": "2019-08-24T14:15:22Z",
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "injected": true,
              "input": "string",
              "interception_id": "34d9b688-63ad-46f4-88b5-665c1e7f7824",
              "metadata": {
                "property1": null,
                "property2": null
              },
              "provider_response_id": "string",
              "server_url": "string",
              "tool": "string"
            }
          ]
        }
      ],
      "attribution": {
        "property1": "string",
        "property2": "string"
      },
      "credential_hint": "string",
      "credential_kind": "string",
      "ended_at": "2019-08-24T14:15:22Z",
      "error_message": "string",
      "error_type": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "model": "string",
      "organization": {
        "display_name": "string",
        "icon": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "source": "workspace"
      },
      "priced_model": {
        "cache_read_price": 0,
        "cache_write_price": 0,
        "input_price": 0,
        "model": "string",
        "output_price": 0
      },
      "prompt": "string",
      "provider": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "token_usage": {
        "cache_read_input_tokens": 0,
        "cache_write_input_tokens": 0,
        "cost_micros": 0,
        "has_unpriced_usage": true,
        "input_tokens": 0,
        "metadata": {
          "property1": null,
          "property2": null
        },
        "output_tokens": 0
      }
    }
  ],
  "token_usage_summary": {
    "cache_read_input_tokens": 0,
    "cache_write_input_tokens": 0,
    "cost_micros": 0,
    "has_unpriced_usage": true,
    "input_tokens": 0,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "output_tokens": 0
  }
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.AIBridgeSessionThreadsResponse

To perform this operation, you must be authenticated. Learn more.