systemprompt_models/modules/
api_paths.rs

1//! API path constants.
2//!
3//! Copyright (c) systemprompt.io — Business Source License 1.1.
4//! See <https://systemprompt.io> for licensing details.
5
6use systemprompt_identifiers::{AgentName, ClientId, ContentHash, PluginId, TenantId};
7
8#[derive(Debug, Clone, Copy)]
9pub struct ApiPaths;
10
11impl ApiPaths {
12    pub const GATEWAY_BASE: &'static str = "/v1";
13    pub const GATEWAY_PUBLIC_BASE: &'static str = "/api/public/gateway";
14
15    pub const API_BASE: &'static str = "/api";
16    pub const API_V1: &'static str = "/api/v1";
17    pub const CORE_BASE: &'static str = "/api/v1/core";
18    pub const AGENTS_BASE: &'static str = "/api/v1/agents";
19    pub const MCP_BASE: &'static str = "/api/v1/mcp";
20    pub const STREAM_BASE: &'static str = "/api/v1/stream";
21    pub const CONTENT_BASE: &'static str = "/api/v1/content";
22    pub const SYNC_BASE: &'static str = "/api/v1/sync";
23    pub const ANALYTICS_BASE: &'static str = "/api/v1/analytics";
24    pub const META_BASE: &'static str = "/api/v1/meta";
25    pub const SLACK_BASE: &'static str = "/api/v1/slack";
26    pub const TEAMS_BASE: &'static str = "/api/v1/teams";
27
28    pub const CORE_CONTEXTS: &'static str = "/api/v1/core/contexts";
29    pub const CORE_TASKS: &'static str = "/api/v1/core/tasks";
30    pub const CORE_ARTIFACTS: &'static str = "/api/v1/core/artifacts";
31
32    pub const AGENT_RUNS: &'static str = "/api/v1/agent-runs";
33
34    pub const AGENTS_REGISTRY: &'static str = "/api/v1/agents/registry";
35
36    pub const MCP_REGISTRY: &'static str = "/api/v1/mcp/registry";
37
38    pub const STREAM_CONTEXTS: &'static str = "/api/v1/stream/contexts";
39
40    pub const AUTH_ME: &'static str = "/api/v1/auth/me";
41
42    pub const OAUTH_BASE: &'static str = "/api/v1/core/oauth";
43    pub const OAUTH_AUTHORIZE: &'static str = "/api/v1/core/oauth/authorize";
44    pub const OAUTH_TOKEN: &'static str = "/api/v1/core/oauth/token";
45    pub const OAUTH_CLIENTS: &'static str = "/api/v1/core/oauth/clients";
46
47    pub const CORE_USERS: &'static str = "/api/v1/core/users";
48
49    pub const WEBHOOK: &'static str = "/api/v1/webhook";
50
51    pub const HEALTH: &'static str = "/api/v1/health";
52
53    pub const LIVEZ: &'static str = "/livez";
54
55    pub const READYZ: &'static str = "/readyz";
56    pub const DISCOVERY: &'static str = "/api/v1";
57
58    pub const WELLKNOWN_BASE: &'static str = "/.well-known";
59    pub const WELLKNOWN_AGENT_CARD: &'static str = "/.well-known/agent-card.json";
60    pub const WELLKNOWN_AGENT_CARDS: &'static str = "/.well-known/agent-cards";
61    pub const WELLKNOWN_OAUTH_SERVER: &'static str = "/.well-known/oauth-authorization-server";
62    pub const WELLKNOWN_OPENID_CONFIG: &'static str = "/.well-known/openid-configuration";
63    pub const WELLKNOWN_OAUTH_PROTECTED: &'static str = "/.well-known/oauth-protected-resource";
64    pub const WELLKNOWN_JWKS: &'static str = "/.well-known/jwks.json";
65    pub const WELLKNOWN_BRIDGE: &'static str = "/.well-known/systemprompt-bridge";
66
67    pub const A2A_CARD: &'static str = "/api/a2a/card";
68
69    pub const ASSETS_BASE: &'static str = "/assets";
70    pub const FILES_BASE: &'static str = "/files";
71    pub const GENERATED_BASE: &'static str = "/generated";
72    pub const IMAGES_BASE: &'static str = "/images";
73    pub const STATIC_BASE: &'static str = "/static";
74    pub const NEXT_BASE: &'static str = "/_next";
75    pub const DOCS_BASE: &'static str = "/docs";
76    pub const SWAGGER_BASE: &'static str = "/swagger";
77    pub const OPENAPI_BASE: &'static str = "/openapi";
78
79    pub const TRACK_BASE: &'static str = "/track";
80    pub const TRACK_ENGAGEMENT: &'static str = "/track/engagement";
81
82    pub const ADMIN_BASE: &'static str = "/api/v1/admin";
83
84    pub const MARKETPLACE_BASE: &'static str = "/api/v1/marketplace";
85
86    pub const CLOUD_TENANTS: &'static str = "/api/v1/tenants";
87
88    pub const BRIDGE_BASE: &'static str = "/v1/bridge";
89    pub const BRIDGE_PUBKEY: &'static str = "/v1/bridge/pubkey";
90    pub const BRIDGE_MANIFEST: &'static str = "/v1/bridge/manifest";
91    pub const BRIDGE_PLUGINS: &'static str = "/v1/bridge/plugins";
92    pub const BRIDGE_PLUGIN_FILE_ROUTE: &'static str = "/v1/bridge/plugins/{plugin_id}/{*path}";
93    pub const BRIDGE_LATEST: &'static str = "/v1/bridge/latest";
94    pub const BRIDGE_DOWNLOAD: &'static str = "/v1/bridge/download";
95    pub const BRIDGE_DOWNLOAD_ROUTE: &'static str = "/v1/bridge/download/{platform}";
96    pub const BRIDGE_WHOAMI: &'static str = "/v1/bridge/whoami";
97    pub const BRIDGE_PROFILE: &'static str = "/v1/bridge/profile";
98    pub const BRIDGE_PROFILE_ENABLED_HOSTS: &'static str = "/v1/bridge/profile/enabled_hosts";
99    pub const BRIDGE_PROFILE_HOST_MODEL_FILTER: &'static str =
100        "/v1/bridge/profile/host-model-filter";
101    pub const BRIDGE_PROFILE_USAGE: &'static str = "/v1/bridge/profile/usage";
102    pub const BRIDGE_DEVICE: &'static str = "/v1/bridge/device";
103    pub const BRIDGE_HEARTBEAT: &'static str = "/v1/bridge/heartbeat";
104    pub const BRIDGE_STREAM: &'static str = "/v1/bridge/stream";
105    pub const BRIDGE_NOTIFICATIONS: &'static str = "/v1/bridge/notifications";
106    pub const BRIDGE_NOTIFICATIONS_READ: &'static str = "/v1/bridge/notifications/read";
107    pub const BRIDGE_NOTIFICATIONS_SEEN: &'static str = "/v1/bridge/notifications/seen";
108    pub const BRIDGE_NOTIFICATIONS_ESCALATE_ROUTE: &'static str =
109        "/v1/bridge/notifications/{id}/escalate";
110    pub const BRIDGE_NOTIFICATIONS_SUBSCRIPTIONS: &'static str =
111        "/v1/bridge/notifications/subscriptions";
112    pub const BRIDGE_NOTIFICATIONS_SUBSCRIPTION_ROUTE: &'static str =
113        "/v1/bridge/notifications/subscriptions/{id}";
114    pub const BRIDGE_NOTIFICATIONS_STREAMS: &'static str = "/v1/bridge/notifications/streams";
115    pub const BRIDGE_DRIVE_MANIFEST: &'static str = "/v1/bridge/drive/manifest";
116    pub const BRIDGE_DRIVE_CHANGES: &'static str = "/v1/bridge/drive/changes";
117    pub const BRIDGE_DRIVE_BLOB: &'static str = "/v1/bridge/drive/blob";
118    pub const BRIDGE_DRIVE_BLOB_ROUTE: &'static str = "/v1/bridge/drive/blob/{sha256}";
119    pub const BRIDGE_DRIVE_COMMIT: &'static str = "/v1/bridge/drive/commit";
120    pub const BRIDGE_DRIVE_PRESENCE: &'static str = "/v1/bridge/drive/presence";
121    pub const BRIDGE_DRIVE_PROPOSALS: &'static str = "/v1/bridge/drive/proposals";
122    pub const BRIDGE_DRIVE_TOKEN: &'static str = "/v1/bridge/drive/token";
123    pub const DOCUMENTS: &'static str = "/api/v1/documents";
124    pub const DOCUMENT_FOLDERS: &'static str = "/api/v1/document-folders";
125    pub const UPLOADS: &'static str = "/api/v1/uploads";
126    pub const NOTIFICATIONS: &'static str = "/api/v1/notifications";
127    pub const NOTIFICATIONS_SEEN: &'static str = "/api/v1/notifications/seen";
128    pub const ADMIN_NOTIFICATIONS: &'static str = "/api/v1/admin/notifications";
129    pub const BRAIN: &'static str = "/api/v1/brain";
130    pub const ADMIN_BRAIN: &'static str = "/api/v1/admin/brain";
131    pub const BRIDGE_AUTH_PAT: &'static str = "/v1/auth/bridge/pat";
132    pub const BRIDGE_AUTH_SESSION: &'static str = "/v1/auth/bridge/session";
133    pub const BRIDGE_AUTH_SESSION_PAT: &'static str = "/v1/auth/bridge/session-pat";
134    pub const BRIDGE_AUTH_OAUTH_CLIENT: &'static str = "/v1/auth/bridge/oauth-client";
135    pub const BRIDGE_AUTH_CAPABILITIES: &'static str = "/v1/auth/bridge/capabilities";
136    pub const BRIDGE_PERSONAL_KEYS: &'static str = "/v1/me/provider-credentials";
137    pub const OTEL: &'static str = "/otel";
138    pub const OTEL_REST_ROUTE: &'static str = "/otel/{*rest}";
139    pub const MCP: &'static str = "/mcp";
140    pub const PUBLIC_HOOKS: &'static str = "/api/public/hooks";
141    pub const PUBLIC_HOOKS_TRACK: &'static str = "/api/public/hooks/track";
142    pub const CONSUMER_RECEIPTS: &'static str = "/api/v1/consumer/receipts";
143    pub const CONSUMER_SESSION_BINDINGS: &'static str = "/api/v1/consumer/session-bindings";
144    pub const CONSUMER_DEVICE_ENROLLMENT: &'static str = "/api/v1/consumer-devices/enrollment";
145    pub const CONSUMER_BUNDLE_ROUTE: &'static str =
146        "/api/v1/consumer/resources/{resource}/publications/{publication}/bundle";
147
148    // Why: `/otel` and `/mcp` are route families, not single endpoints; the
149    // bare path and every path below it belong to the family and nothing that
150    // merely shares the prefix (`/otelx`, `/mcpx`) does. Stated once here so
151    // the server's routing and the bridge's credential scoping cannot disagree.
152    #[must_use]
153    pub fn is_otel(path: &str) -> bool {
154        Self::in_family(path, Self::OTEL)
155    }
156
157    #[must_use]
158    pub fn is_mcp(path: &str) -> bool {
159        Self::in_family(path, Self::MCP)
160    }
161
162    #[must_use]
163    pub fn is_public_hook(path: &str) -> bool {
164        path.len() > Self::PUBLIC_HOOKS.len() + 1 && Self::in_family(path, Self::PUBLIC_HOOKS)
165    }
166
167    fn in_family(path: &str, base: &str) -> bool {
168        path == base
169            || path
170                .strip_prefix(base)
171                .is_some_and(|rest| rest.starts_with('/'))
172    }
173
174    #[must_use]
175    pub fn mcp_server_slug(path: &str) -> Option<&str> {
176        let rest = path.strip_prefix(Self::MCP)?.strip_prefix('/')?;
177        let slug = rest.split('/').next()?;
178        (!slug.is_empty()).then_some(slug)
179    }
180
181    #[must_use]
182    pub fn gateway_relative(path: &'static str) -> &'static str {
183        path.strip_prefix(Self::GATEWAY_BASE).unwrap_or(path)
184    }
185
186    #[must_use]
187    pub fn api_v1_relative(path: &'static str) -> &'static str {
188        path.strip_prefix(Self::API_V1).unwrap_or(path)
189    }
190
191    pub fn bridge_plugin_file(plugin_id: &PluginId, relative_path: &str) -> String {
192        format!(
193            "{}/{}/{relative_path}",
194            Self::BRIDGE_PLUGINS,
195            plugin_id.as_str()
196        )
197    }
198
199    pub fn bridge_drive_blob(sha256: &ContentHash) -> String {
200        format!("{}/{}", Self::BRIDGE_DRIVE_BLOB, sha256.as_str())
201    }
202
203    pub fn bridge_plugin_archive(plugin_id: &PluginId, sha256: &str) -> String {
204        format!(
205            "{}/{}/archive/{sha256}",
206            Self::BRIDGE_PLUGINS,
207            plugin_id.as_str()
208        )
209    }
210
211    pub fn bridge_download(platform: &str) -> String {
212        format!("{}/{platform}", Self::BRIDGE_DOWNLOAD)
213    }
214
215    pub fn otel_under(base_url: &str) -> String {
216        format!("{}{}", base_url.trim_end_matches('/'), Self::OTEL)
217    }
218
219    pub fn tenant(tenant_id: &TenantId) -> String {
220        format!("{}/{}", Self::CLOUD_TENANTS, tenant_id.as_str())
221    }
222
223    pub fn tenant_status(tenant_id: &TenantId) -> String {
224        format!("{}/{}/status", Self::CLOUD_TENANTS, tenant_id.as_str())
225    }
226
227    pub fn tenant_registry_token(tenant_id: &TenantId) -> String {
228        format!(
229            "{}/{}/registry-token",
230            Self::CLOUD_TENANTS,
231            tenant_id.as_str()
232        )
233    }
234
235    pub fn tenant_deploy(tenant_id: &TenantId) -> String {
236        format!("{}/{}/deploy", Self::CLOUD_TENANTS, tenant_id.as_str())
237    }
238
239    pub fn tenant_secrets(tenant_id: &TenantId) -> String {
240        format!("{}/{}/secrets", Self::CLOUD_TENANTS, tenant_id.as_str())
241    }
242
243    pub fn tenant_rotate_credentials(tenant_id: &TenantId) -> String {
244        format!(
245            "{}/{}/rotate-credentials",
246            Self::CLOUD_TENANTS,
247            tenant_id.as_str()
248        )
249    }
250
251    pub fn mcp_server_endpoint(server_name: &str) -> String {
252        format!("{}/{}/mcp", Self::MCP_BASE, server_name)
253    }
254
255    pub fn oauth_client_location(client_id: &ClientId) -> String {
256        format!("{}/{}", Self::OAUTH_CLIENTS, client_id.as_str())
257    }
258
259    pub fn wellknown_agent_card_named(agent_name: &str) -> String {
260        format!("{}/{}", Self::WELLKNOWN_AGENT_CARDS, agent_name)
261    }
262
263    pub fn agent_endpoint(agent_name: &AgentName) -> String {
264        format!("{}/{}/", Self::AGENTS_BASE, agent_name.as_str())
265    }
266}
systemprompt_models/modules/api_paths.rs

systemprompt_models/modules/
api_paths.rs
