API Reference
Complete REST API reference for taco-api, taco-inbound, and taco-auth endpoints.
This documents the REST API served by taco-api on port 8090. All endpoints return JSON.
Authentication
Public Endpoints (no auth required)
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/auth/register | Register a new user account |
| POST | /api/v1/auth/login | Login with email/password |
| POST | /api/v1/auth/refresh | Refresh an access token |
| POST | /api/v1/auth/logout | Logout (invalidate refresh token) |
| GET | /api/v1/auth/github | Initiate GitHub OAuth flow |
| GET | /api/v1/auth/github/callback | GitHub OAuth callback |
| GET | /api/v1/auth/google | Initiate Google OAuth flow |
| GET | /api/v1/auth/google/callback | Google OAuth callback |
| POST | /api/v1/billing/webhook | Stripe webhook (uses Stripe signature verification) |
| GET | /healthz | Health check |
Protected Endpoints
All other endpoints require Authorization: Bearer <jwt_access_token>.
Users
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/users/me | Get current user profile |
| PUT | /api/v1/users/me | Update current user profile |
| PUT | /api/v1/users/me/slack-webhook | Update user-level Slack webhook URL |
Subscriptions
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/subscriptions | any | List user's subscriptions |
| POST | /api/v1/subscriptions | any | Create a new subscription |
| GET | /api/v1/subscriptions/:subscription_id | owner, admin, member | Get subscription details |
| PUT | /api/v1/subscriptions/:subscription_id | owner, admin | Update subscription |
| DELETE | /api/v1/subscriptions/:subscription_id | owner, admin | Delete subscription |
| GET | /api/v1/subscriptions/:subscription_id/components/usage | owner, admin, member | Get component usage stats |
| GET | /api/v1/subscriptions/:subscription_id/members | owner, admin, member | List subscription members |
| POST | /api/v1/subscriptions/:subscription_id/members | owner, admin | Invite a member |
| PUT | /api/v1/subscriptions/:subscription_id/members/:user_id | owner, admin | Update member role |
| DELETE | /api/v1/subscriptions/:subscription_id/members/:user_id | owner, admin | Remove a member |
| GET | /api/v1/subscriptions/:subscription_id/stats | owner, admin, member | Get subscription statistics |
| PUT | /api/v1/subscriptions/:subscription_id/slack-webhook | owner, admin | Update subscription Slack webhook |
| GET | /api/v1/subscriptions/:subscription_id/dashboard | owner, admin, member | Get subscription dashboard data |
Billing
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/subscriptions/:subscription_id/billing | owner, admin, member | Get billing status |
| POST | /api/v1/subscriptions/:subscription_id/billing/checkout | owner, admin | Create Stripe checkout session |
| POST | /api/v1/subscriptions/:subscription_id/billing/portal | owner, admin | Create Stripe customer portal session |
Projects
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/subscriptions/:subscription_id/projects | owner, admin, member | List projects in subscription |
| POST | /api/v1/subscriptions/:subscription_id/projects | owner, admin | Create a project |
| GET | /api/v1/projects/:project_id | owner, admin, member | Get project details |
| PUT | /api/v1/projects/:project_id | owner, admin | Update project |
| DELETE | /api/v1/projects/:project_id | owner, admin | Delete project |
| GET | /api/v1/projects/:project_id/stats | owner, admin, member | Get project statistics |
| GET | /api/v1/projects/:project_id/dashboard | owner, admin, member | Get project dashboard data |
Project Members
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/members | owner, admin, member | List project members |
| POST | /api/v1/projects/:project_id/members | owner, admin | Add a project member |
| PUT | /api/v1/projects/:project_id/members/:user_id | owner, admin | Update member role |
| DELETE | /api/v1/projects/:project_id/members/:user_id | owner, admin | Remove a member |
SBOMs
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/sboms | owner, admin, member | List SBOMs for a project |
| GET | /api/v1/projects/:project_id/sboms/:sbom_id | owner, admin, member | Get SBOM details |
| GET | /api/v1/projects/:project_id/sboms/:sbom_id/findings | owner, admin, member | List findings for a specific SBOM |
| GET | /api/v1/projects/:project_id/sboms/diff/:sbom_a/:sbom_b | owner, admin, member | Diff two SBOMs |
| GET | /api/v1/projects/:project_id/sboms/aggregate | owner, admin, member | Aggregate SBOM statistics |
Components
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/components | owner, admin, member | List components in a project |
| GET | /api/v1/projects/:project_id/components/summary | owner, admin, member | Get component summary stats |
| GET | /api/v1/projects/:project_id/components/:component_id | owner, admin, member | Get component details |
| GET | /api/v1/projects/:project_id/components/:component_id/dependencies | owner, admin, member | Get component dependency tree |
| PUT | /api/v1/projects/:project_id/components/:component_id/status | owner, admin, member | Set component triage status |
| DELETE | /api/v1/projects/:project_id/components/:component_id/status | owner, admin, member | Clear component triage status |
| POST | /api/v1/projects/:project_id/components/bulk-status | owner, admin, member | Bulk set component statuses |
Findings
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/findings/recent | any (JWT) | Get recent findings across all user's projects |
| GET | /api/v1/projects/:project_id/findings | owner, admin, member | List findings for a project |
| GET | /api/v1/projects/:project_id/findings/summary | owner, admin, member | Get findings summary (counts by severity) |
| GET | /api/v1/projects/:project_id/findings/trends | owner, admin, member | Get finding trends over time |
| GET | /api/v1/projects/:project_id/findings/cve/:cve_id | owner, admin, member | Get details for a specific CVE |
Secrets
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/secrets | owner, admin, member | List detected secrets |
| GET | /api/v1/projects/:project_id/secrets/summary | owner, admin, member | Get secrets summary |
| GET | /api/v1/projects/:project_id/secrets/:secret_id | owner, admin, member | Get secret details |
| PUT | /api/v1/projects/:project_id/secrets/:secret_id/status | owner, admin, member | Set secret triage status |
| DELETE | /api/v1/projects/:project_id/secrets/:secret_id/status | owner, admin, member | Clear secret triage status |
Tokens
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/tokens | owner, admin, member | List project tokens |
| POST | /api/v1/projects/:project_id/tokens | owner, admin | Create a project token |
| DELETE | /api/v1/projects/:project_id/tokens/:token_id | owner, admin | Revoke a project token |
Alerts
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/alerts | owner, admin, member | Get alert configuration |
| PUT | /api/v1/projects/:project_id/alerts | owner, admin | Update alert configuration |
| GET | /api/v1/projects/:project_id/alerts/webhook | owner, admin, member | Get effective webhook URL |
Scan Requests
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/scan-requests | owner, admin, member | Get scan request status |
| POST | /api/v1/projects/:project_id/sboms/:sbom_id/scan | owner, admin, member | Request an on-demand scan |
Image Scans
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/image-scans | owner, admin, member | List image scan requests |
| POST | /api/v1/projects/:project_id/image-scans | owner, admin, member | Request a container image scan |
Risk Configuration
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/risk-config | owner, admin, member | Get risk scoring configuration |
| PUT | /api/v1/projects/:project_id/risk-config | owner, admin | Update risk scoring configuration |
Audit Log
| Method | Endpoint | Roles | Description |
|---|---|---|---|
| GET | /api/v1/projects/:project_id/audit-log | owner, admin, member | List audit log entries |
Inbound API (taco-inbound)
These endpoints are served by taco-inbound at taco-inbound.taco-sec.com.
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/v1/sbom | Bearer project-token | Submit an SBOM for processing |
| POST | /api/v1/secrets | Bearer project-token | Submit secret scan results |
| GET | /healthz | none | Health check |
| GET | /swagger/* | none | Swagger UI |
Auth Service API (taco-auth, internal)
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/token/validate?token=<token> | Validate a project token |
| GET | /healthz | Health check |
| GET | /swagger/* | Swagger UI |