SerenAI API Documentation

agent

Agent commerce and paid query execution

POST /auth/agent

POST /auth/agent Register a new AI agent account.

This endpoint allows AI agents to self-register and receive an API key immediately.
Unlike the standard signup flow, agent registration:
- Does NOT require email verification
- Automatically creates a personal organization
- Returns an API key named "agent" for immediate use

**Important:** Save the `api_key` immediately - it is only shown once!

Operation: agent_register

Request Body (required)

AgentRegisterRequest

name: string,null — Optional custom display name for the agent. If not provided, a unique celestial-

Responses

201 Agent registered successfully

AgentRegisterDataResponse

data*: AgentRegisterResponse — The actual response data

400 Invalid request (validation error)

500 Internal server error

PATCH /auth/agent

Update an agent's profile (e.g. set a real email address).

When the email is changed, `email_verified` is set to `false` and a
verification email with a clickable link is sent. The user verifies
by clicking the link — no separate API call is needed.
A verified email is required before making Stripe deposits.

Operation: agent_update

Request Body (required)

AgentUpdateRequest

email*: string — Email address to set and verify. A verification email will be sent to this addre

Responses

200 Agent updated

400 Invalid email

401 Unauthorized

Databases

Database management endpoints

GET /databases

List all databases across all projects for the authenticated user

Returns all databases the user has access to, with project and branch context included.
This provides a single view of all databases without needing to query each project/branch separately.

Operation: list_all_databases

Responses

200 List of all databases with context

DataResponse_Vec_DatabaseWithContext

data*: array

pagination: any

401 Unauthorized

Auth

Authentication and user management endpoints

POST /auth/forgot-password

POST /auth/forgot-password Request a password reset email

Operation: forgot_password

Request Body (required)

ForgotPasswordRequest

email*: Email

Responses

200 Password reset email sent if account exists

DataResponse_PasswordResetSent

data*: object

pagination: any

400 Invalid request

GET /auth/me

GET /auth/me Get current authenticated user information with default organization

Operation: get_current_user

Responses

200 Current user information with default organization

DataResponse_UserMe

data*: any — Response for GET /auth/me - current user info with default organization

pagination: any

401 Unauthorized

POST /auth/resend-verification

POST /auth/resend-verification Resend email verification link

Operation: resend_verification_email

Request Body (required)

ResendVerificationRequest

email*: Email

Responses

200 Verification email sent if account exists

DataResponse_VerificationSent

data*: object

pagination: any

400 Invalid request

POST /auth/reset-password

POST /auth/reset-password Reset password using a valid token

Operation: reset_password

Request Body (required)

ResetPasswordRequest

new_password*: string

token*: string

Responses

200 Password reset successfully

DataResponse_PasswordReset

data*: object

pagination: any

400 Invalid or expired token

404 Token not found

POST /auth/verify-email

POST /auth/verify-email Verify email address using a token from the verification email link. Called by the console frontend when the user clicks the link — agents do not need to call this directly. On success, automatically logs the user in and returns tokens

Operation: verify_email

Request Body (required)

VerifyEmailRequest

token*: string

Responses

200 Email verified and user logged in

DataResponse_LoginResult

data*: object

pagination: any

400 Invalid or expired token

GET /organizations/default/api-keys

List API keys for the user's default organization

Operation: list_default_org_api_keys

Responses

200 List of API keys

DataResponse_Vec_ApiKeyInfo

data*: array

pagination: any

400 User has no organization

401 Unauthorized

POST /organizations/default/api-keys

Create a new API key for the user's default organization

This is a convenience endpoint that resolves "default" to the user's
first organization, avoiding an extra round-trip to /auth/me.

Operation: create_default_org_api_key

Request Body (required)

CreateApiKeyRequest

expires_in_days: integer,null

name*: string

Responses

201 API key created

DataResponse_ApiKeyCreated

data*: object — Response struct for API key creation (includes the full key ONCE)

pagination: any

400 User has no organization

401 Unauthorized

DELETE /organizations/default/api-keys/{key_id}

Revoke an API key from the user's default organization

Operation: revoke_default_org_api_key

Parameters

Name	In	Type	Required	Description
`key_id`	path	string	Yes	API key ID

Responses

200 API key revoked

400 User has no organization

401 Unauthorized

404 API key not found

GET /organizations/{organization_id}/api-keys

List API keys for a specific organization

Operation: list_org_api_keys

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 List of API keys

DataResponse_Vec_ApiKeyInfo

data*: array

pagination: any

401 Unauthorized

404 Organization not found

POST /organizations/{organization_id}/api-keys

Create a new API key for a specific organization

Operation: create_org_api_key

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Request Body (required)

CreateApiKeyRequest

expires_in_days: integer,null

name*: string

Responses

201 API key created

DataResponse_ApiKeyCreated

data*: object — Response struct for API key creation (includes the full key ONCE)

pagination: any

401 Unauthorized

404 Organization not found

DELETE /organizations/{organization_id}/api-keys/{key_id}

Revoke an organization API key

Operation: revoke_org_api_key

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`key_id`	path	string	Yes	API key ID

Responses

200 API key revoked

401 Unauthorized

404 API key not found

OAuth

OAuth connections for BYOC integrations

GET /oauth/connections

List user's OAuth connections

Returns all OAuth providers the user has connected to.

Operation: list_connections

Responses

200 List of user's OAuth connections

ConnectionsResponse

connections*: array

DELETE /oauth/connections/providers/{provider_id}

Revoke an OAuth connection by provider ID (supports org-scoped providers)

Operation: revoke_connection_by_id

Parameters

Name	In	Type	Required	Description
`provider_id`	path	string	Yes	OAuth provider UUID to disconnect

Responses

200 Connection revoked successfully

RevokeResponse

message*: string

success*: boolean

404 Connection not found

DELETE /oauth/connections/{provider}

Revoke an OAuth connection

Disconnects the user's account from the OAuth provider and deletes stored tokens.

Operation: revoke_connection

Parameters

Name	In	Type	Required	Description
`provider`	path	string	Yes	OAuth provider slug to disconnect

Responses

200 Connection revoked successfully

RevokeResponse

message*: string

success*: boolean

404 Connection not found

GET /oauth/providers

List available OAuth providers

Returns all active OAuth providers that users can connect to,
including global providers and providers from organizations the user belongs to.

Operation: list_providers

Responses

200 List of available OAuth providers

ProvidersResponse

providers*: array

GET /oauth/providers/{provider_id}/authorize

Initiate OAuth authorization flow by provider ID (supports org-scoped providers)

Operation: initiate_oauth_by_id

Parameters

Name	In	Type	Required	Description
`provider_id`	path	string	Yes	OAuth provider UUID
`redirect_uri`	query	string	No	Where to redirect after OAuth completes

Responses

302 Redirect to OAuth provider

404 Provider not found

GET /oauth/providers/{provider_id}/callback

Handle OAuth callback by provider ID (supports org-scoped providers)

Operation: oauth_callback_by_id

Parameters

Name	In	Type	Required	Description
`provider_id`	path	string	Yes	OAuth provider UUID
`code`	query	string	Yes	Authorization code from provider
`state`	query	string	Yes	State parameter for CSRF verification

Responses

302 Redirect to frontend with success/error

400 Invalid callback parameters

404 Provider not found

GET /oauth/{provider}/authorize

Initiate OAuth authorization flow

Redirects the user to the OAuth provider's consent screen.
After authorization, the provider will redirect back to the callback URL.

Operation: initiate_oauth

Parameters

Name	In	Type	Required	Description
`provider`	path	string	Yes	OAuth provider slug (e.g., 'neon')
`redirect_uri`	query	string	No	Where to redirect after OAuth completes

Responses

302 Redirect to OAuth provider

404 Provider not found

GET /oauth/{provider}/callback

Handle OAuth callback

Called by the OAuth provider after the user authorizes.
Exchanges the authorization code for tokens and stores them.

Operation: oauth_callback

Parameters

Name	In	Type	Required	Description
`provider`	path	string	Yes	OAuth provider slug
`code`	query	string	Yes	Authorization code from provider
`state`	query	string	Yes	State parameter for CSRF verification

Responses

302 Redirect to frontend with success/error

400 Invalid callback parameters

oauth-providers

Organization OAuth provider configuration (BYOC)

GET /organizations/{organization_id}/oauth/providers

GET /organizations/{organization_id}/oauth/providers

List all OAuth providers for an organization.

Operation: list_org_oauth_providers

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 List of OAuth providers

OAuthProvidersDataResponse

data*: array

401 Unauthorized

403 Forbidden - not a member of the organization

500 Internal server error

POST /organizations/{organization_id}/oauth/providers

POST /organizations/{organization_id}/oauth/providers

Create a new OAuth provider for an organization.

Operation: create_org_oauth_provider

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Request Body (required)

CreateOAuthProviderRequest

authorization_url*: string

client_id*: string

client_secret*: string — Client secret (will be encrypted)

custom_auth_params: any — Custom provider-specific authorization URL parameters (e.g., {"access_type": "of

description: string,null

logo_url: string,null

name*: string

pkce_required: boolean

revocation_url: string,null

scopes*: array

... and 4 more properties

Responses

201 OAuth provider created

OAuthProviderDataResponse

data*: OAuthProviderResponse

400 Invalid request

401 Unauthorized

403 Forbidden - not a member of the organization

409 Conflict - provider with this slug already exists

500 Internal server error

GET /organizations/{organization_id}/oauth/providers/{provider_id}

GET /organizations/{organization_id}/oauth/providers/{provider_id}

Get a specific OAuth provider for an organization.

Operation: get_org_oauth_provider

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`provider_id`	path	string	Yes	OAuth provider ID

Responses

200 OAuth provider details

OAuthProviderDataResponse

data*: OAuthProviderResponse

401 Unauthorized

403 Forbidden - not a member of the organization

404 Provider not found

500 Internal server error

DELETE /organizations/{organization_id}/oauth/providers/{provider_id}

DELETE /organizations/{organization_id}/oauth/providers/{provider_id}

Delete an OAuth provider for an organization.

Operation: delete_org_oauth_provider

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`provider_id`	path	string	Yes	OAuth provider ID

Responses

204 OAuth provider deleted

401 Unauthorized

403 Forbidden - not a member of the organization

404 Provider not found

500 Internal server error

PATCH /organizations/{organization_id}/oauth/providers/{provider_id}

PATCH /organizations/{organization_id}/oauth/providers/{provider_id}

Update an OAuth provider for an organization.

Operation: update_org_oauth_provider

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`provider_id`	path	string	Yes	OAuth provider ID

Request Body (required)

UpdateOAuthProviderRequest

authorization_url: string,null

client_id: string,null

client_secret: string,null — Optional new client secret (will be re-encrypted). If omitted, keep existing.

custom_auth_params: any — Custom provider-specific authorization URL parameters. If omitted, leave unchang

description: string,null — If omitted, leave unchanged. If null, clear.

is_active: boolean,null

logo_url: string,null — If omitted, leave unchanged. If null, clear.

organization_id: string,null — If omitted, leave unchanged. If null, make global. If set, scope to organization

pkce_required: boolean,null

... and 6 more properties

Responses

200 OAuth provider updated

OAuthProviderDataResponse

data*: OAuthProviderResponse

400 Invalid request

401 Unauthorized

403 Forbidden - not a member of the organization

404 Provider not found

409 Conflict - provider with this slug already exists

500 Internal server error

Organizations

Organization management endpoints

GET /organizations

GET /organizations List all organizations for the authenticated user

Operation: list_organizations

Responses

200 List of organizations

DataResponse_Vec_Organization

data*: array

pagination: any

401 Unauthorized

GET /organizations/{organization_id}/invites

GET /organizations/{organization_id}/invites List pending and historical organization invites.

Operation: list_invites

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 Organization invites retrieved

DataResponse_Vec_OrganizationInvite

data*: array

pagination: any

403 User is not allowed to view invites

500 Internal server error

POST /organizations/{organization_id}/invites

POST /organizations/{organization_id}/invites Create a new organization invite and send an email via the configured mailer.

Operation: create_invite

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Request Body (required)

CreateOrganizationInviteRequest

email*: string — Email address of the invitee.

role: string,null — Optional role for the invitee (defaults to member).

Responses

201 Invite created and email sent

DataResponse_OrganizationInvite

data*: object — Response type for organization invites (token is not exposed over the API).

pagination: any

400 Invalid request

403 User is not allowed to create invites

500 Internal server error

GET /organizations/{organization_id}/members

GET /organizations/{organization_id}/members List organization members with basic user details.

Operation: list_members

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 Organization members retrieved

DataResponse_Vec_OrganizationMemberWithUser

data*: array

pagination: any

403 User is not a member of the organization

500 Internal server error

GET /organizations/{organization_id}/publishers

GET /organizations/:org_id/publishers List publishers owned by an organization

Operation: list_org_publishers

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 Publishers retrieved successfully

DataResponse_Vec_PublisherResponse

data*: array

pagination: any

403 Not authorized

500 Internal server error

POST /organizations/{organization_id}/publishers

POST /organizations/:org_id/publishers Create a new publisher

Operation: create_publisher

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Request Body (required)

CreatePublisherRequest

a2a_endpoint_url: string,null — A2A endpoint base URL (required for compute_type = agent)

accepted_asset_ids: array,null — Asset IDs the publisher accepts for payment

allowed_passthrough_headers: array — Whitelist of agent-provided headers allowed to pass through to upstream

api_headers: any — Headers for API requests (will be encrypted)

api_key_header: string,null — Header name to inject upstream_api_key into (e.g., "Authorization", "X-API-Key")

api_key_query_param: string,null — Query parameter name to inject upstream_api_key into (e.g., "api_key")

api_url: string,null — External API URL (required for integration_type = api)

auth_type: string,null — Upstream auth mode ("static", "jwt", or "oauth2_cc") (default: static)

base_price_per_1000_rows: string,null

billing_model: string,null — Billing model ("x402_per_request", "prepaid_credits", "x402_passthrough", "pay_p

... and 64 more properties

Responses

201 Publisher created successfully

DataResponse_PublisherResponse

data*: object — Publisher response (excludes sensitive fields)

pagination: any

400 Invalid request

403 Not authorized

409 Publisher slug already exists

500 Internal server error

GET /organizations/{organization_id}/publishers/{publisher_id}

GET /organizations/:org_id/publishers/:publisher_id Get publisher details

Operation: get_org_publisher

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID

Responses

200 Publisher retrieved successfully

DataResponse_PublisherResponse

data*: object — Publisher response (excludes sensitive fields)

pagination: any

403 Not authorized

404 Publisher not found

500 Internal server error

PUT /organizations/{organization_id}/publishers/{publisher_id}

PUT /organizations/:org_id/publishers/:publisher_id Update a publisher

Operation: update_publisher

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID

Request Body (required)

UpdatePublisherRequest

a2a_endpoint_url: string,null — A2A endpoint base URL (for compute_type = agent)

add_asset_ids: array,null — Asset IDs to add to accepted assets

allowed_passthrough_headers: array,null — Whitelist of agent-provided headers allowed to pass through to upstream

api_headers: any — Headers for API requests (will be encrypted)

api_key_header: string,null — Header name to inject upstream_api_key into (e.g., "Authorization", "X-API-Key")

api_key_query_param: string,null — Query parameter name to inject upstream_api_key into (e.g., "api_key")

api_url: string,null — External API URL (for integration_type = api)

auth_type: string,null — Upstream auth mode ("static" or "jwt")

base_price_per_1000_rows: string,null

billing_model: string,null — Billing model ("x402_per_request", "prepaid_credits", "x402_passthrough", "pay_p

... and 64 more properties

Responses

200 Publisher updated successfully

DataResponse_PublisherResponse

data*: object — Publisher response (excludes sensitive fields)

pagination: any

400 Invalid request

403 Not authorized

404 Publisher not found

500 Internal server error

DELETE /organizations/{organization_id}/publishers/{publisher_id}

DELETE /organizations/:org_id/publishers/:publisher_id Soft delete a publisher

Operation: delete_publisher

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID

Responses

200 Publisher deleted successfully

403 Not authorized

404 Publisher not found

500 Internal server error

GET /organizations/{organization_id}/publishers/{publisher_id}/earnings

GET /organizations/:org_id/publishers/:publisher_id/earnings List earnings for a publisher (per asset).

Operation: get_org_publisher_earnings

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID

Responses

200 Earnings retrieved successfully

DataResponse_Vec_PublisherEarningsResponse

data*: array

pagination: any

403 Not authorized

404 Publisher not found

500 Internal server error

POST /organizations/{organization_id}/publishers/{publisher_id}/logo

POST /organizations/{organization_id}/publishers/{publisher_id}/logo Upload a logo for a publisher

Operation: upload_publisher_logo

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID

Request Body (required)

LogoUploadRequest

content_type*: string — Content type of the image (image/png, image/jpeg, image/webp, image/svg+xml)

logo*: string — Base64 encoded image data

Responses

200 Logo uploaded successfully

DataResponse_LogoUploadResponse

data*: object — Logo upload response

pagination: any

400 Invalid image format or size

403 Not authorized

404 Publisher not found

500 Internal server error

GET /organizations/{organization_id}/publishers/{publisher_id}/payouts

GET /organizations/:org_id/publishers/:publisher_id/payouts List payout requests for a publisher.

Operation: list_org_publisher_payouts

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID
`limit`	query	integer,null	No	Maximum number of results (default: 50)
`offset`	query	integer,null	No	Offset for pagination

Responses

200 Payouts retrieved successfully

DataResponse_Vec_PublisherPayoutResponse

data*: array

pagination: any

403 Not authorized

404 Publisher not found

500 Internal server error

POST /organizations/{organization_id}/publishers/{publisher_id}/payouts

POST /organizations/:org_id/publishers/:publisher_id/payouts Request a payout for a publisher's earnings.

Operation: create_org_publisher_payout

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID

Request Body (required)

CreatePublisherPayoutRequest

amount_atomic: integer,null — Amount to withdraw in atomic units (defaults to max available)

asset_id*: string — Asset to withdraw (must be an asset accepted by the publisher)

destination_wallet: any

Responses

201 Payout request created

DataResponse_PublisherPayoutResponse

data*: object — Publisher payout response.

pagination: any

400 Invalid request

403 Not authorized

404 Publisher not found

500 Internal server error

PUT /organizations/{organization_id}/publishers/{publisher_id}/pricing

PUT /organizations/:org_id/publishers/:publisher_id/pricing Update publisher pricing config for a specific asset

Operation: update_publisher_pricing

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID

Request Body (required)

UpdatePricingRequest

asset_id*: string — Asset ID for this pricing config (required)

base_price_per_1000_rows: string,null

grace_period_minutes: integer,null

hourly_rate: string,null

low_balance_threshold: string,null

markup_multiplier: string,null

max_queries_per_minute: integer,null

min_charge: string,null

min_display_price: string,null — Minimum price to display in UI for passthrough publishers (informational only)

minimum_balance: string,null

... and 19 more properties

Responses

200 Pricing updated successfully

DataResponse_PricingConfigResponse

data*: object — Pricing config response

pagination: any

400 Invalid request

403 Not authorized

404 Publisher not found

500 Internal server error

VPC

VPC endpoint management

GET /organizations/{organization_id}/vpc-endpoints

Operation: list_org_vpc_endpoints

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`region`	query	string,null	No	Filter endpoints by region

Responses

200 List of VPC endpoints

Array<

OrganizationVpcEndpoint

created_at*: string

endpoint_id*: string

id*: string

label: string,null

organization_id*: string

region*: string

state*: string

updated_at*: string

>

401 Unauthorized

404 Organization not found

POST /organizations/{organization_id}/vpc-endpoints

Operation: create_org_vpc_endpoint

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Request Body (required)

CreateOrganizationVpcEndpointRequest

endpoint_id*: string

label: string,null

region*: string

Responses

201 VPC endpoint recorded

DataResponse_OrganizationVpcEndpoint

data*: object

pagination: any

401 Unauthorized

GET /organizations/{organization_id}/vpc-endpoints/{endpoint_id}

Operation: get_org_vpc_endpoint

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`endpoint_id`	path	string	Yes	Organization VPC endpoint ID

Responses

200 VPC endpoint details

DataResponse_OrganizationVpcEndpoint

data*: object

pagination: any

401 Unauthorized

404 VPC endpoint not found

DELETE /organizations/{organization_id}/vpc-endpoints/{endpoint_id}

Operation: delete_org_vpc_endpoint

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`endpoint_id`	path	string	Yes	Organization VPC endpoint ID

Responses

204 VPC endpoint removed

401 Unauthorized

404 VPC endpoint not found

GET /organizations/{organization_id}/vpc/region/{region_id}/vpc_endpoints

List VPC endpoints for an organization filtered by region (alias path)

Operation: list_org_vpc_endpoints_by_region

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`region_id`	path	string	Yes	Region

Responses

200 List of VPC endpoints

Array<

OrganizationVpcEndpoint

created_at*: string

endpoint_id*: string

id*: string

label: string,null

organization_id*: string

region*: string

state*: string

updated_at*: string

>

401 Unauthorized

404 Organization not found

GET /organizations/{organization_id}/vpc/region/{region_id}/vpc_endpoints/{endpoint_id}

Get VPC endpoint details with region in path (alias)

Operation: get_org_vpc_endpoint_by_region

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`region_id`	path	string	Yes	Region
`endpoint_id`	path	string	Yes	Organization VPC endpoint ID

Responses

200 VPC endpoint details

DataResponse_OrganizationVpcEndpoint

data*: object

pagination: any

401 Unauthorized

404 VPC endpoint not found

DELETE /organizations/{organization_id}/vpc/region/{region_id}/vpc_endpoints/{endpoint_id}

Delete VPC endpoint with region in path (alias)

Operation: delete_org_vpc_endpoint_by_region

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`region_id`	path	string	Yes	Region
`endpoint_id`	path	string	Yes	Organization VPC endpoint ID

Responses

204 VPC endpoint removed

401 Unauthorized

404 VPC endpoint not found

GET /organizations/{organization_id}/vpc/vpc_endpoints

List VPC endpoints for an organization (alias path with underscores)

Operation: list_org_vpc_endpoints_alias

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 List of VPC endpoints

Array<

OrganizationVpcEndpoint

created_at*: string

endpoint_id*: string

id*: string

label: string,null

organization_id*: string

region*: string

state*: string

updated_at*: string

>

401 Unauthorized

404 Organization not found

billing

Billing and metering endpoints (x402 token cache)

GET /billing/health

GET /billing/health High-level billing and metering health summary for Seren Core

Operation: get_billing_health

Responses

200 Billing health retrieved successfully

DataResponse_BillingHealth

data*: object — High-level billing health summary.

pagination: any

500 Internal server error

POST /billing/invoices/generate

POST /billing/invoices/generate Generate monthly invoices for all organizations

Operation: generate_invoices

Request Body (required)

GenerateInvoicesRequest

month*: integer

year*: integer

Responses

200 Invoices generated successfully

DataResponse_InvoicesGenerated

data*: object — Response for invoice generation

pagination: any

400 Invalid request

500 Internal server error

GET /billing/invoices/{id}

GET /billing/invoices/:id Get invoice details with line items

Operation: get_invoice

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Invoice ID

Responses

200 Invoice retrieved successfully

DataResponse_Invoice

data*: object — Invoice response with line items

pagination: any

404 Invoice not found

500 Internal server error

POST /billing/invoices/{id}/issue

POST /billing/invoices/:id/issue Issue a draft invoice

Operation: issue_invoice

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Invoice ID

Responses

200 Invoice issued successfully

404 Invoice not found

500 Internal server error

GET /billing/usage/{organization_id}

GET /billing/usage/:organization_id Get usage summary for an organization

Operation: get_usage_summary

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID
`start_date`	query	string,null	No
`end_date`	query	string,null	No

Responses

200 Usage summary retrieved

DataResponse_Vec_UsageSummary

data*: array

pagination: any

404 Organization not found

500 Internal server error

GET /organizations/{organization_id}/billing/endpoints/{endpoint_id}/events

GET /organizations/{organization_id}/billing/endpoints/{endpoint_id}/events Debug endpoint: show recent usage_events and compute_usage_events for an endpoint

Operation: get_endpoint_billing_events

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`endpoint_id`	path	string	Yes	Endpoint ID

Responses

200 Billing events retrieved successfully

DataResponse_EndpointBillingEvents

data*: object — Combined debug response for an endpoint's billing events

pagination: any

404 Endpoint not found for organization

500 Internal server error

GET /organizations/{organization_id}/consumption

GET /organizations/{organization_id}/consumption Aggregated organization-level consumption over a billing window.

Operation: get_organization_consumption

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`start_date`	query	string,null	No	Optional ISO-8601 start date (YYYY-MM-DD), defaults to first day of current month.
`end_date`	query	string,null	No	Optional ISO-8601 end date (YYYY-MM-DD), defaults to today (UTC).

Responses

200 Organization consumption retrieved

DataResponse_OrganizationConsumption

data*: object — OrganizationConsumption wraps organization-wide consumption

pagination: any

401 Unauthorized

403 User is not a member of the organization

500 Internal server error

payments

Stripe payments and payment methods

POST /billing/invoices/{id}/pay

POST /billing/invoices/:id/pay Create a payment intent for an invoice

Operation: create_payment_intent

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Invoice ID

Responses

200 Payment intent created

DataResponse_PaymentIntentCreated

data*: object — Response for creating a payment intent

pagination: any

400 Invoice not in payable state

404 Invoice not found

500 Internal server error

GET /billing/invoices/{id}/payments

GET /billing/invoices/:id/payments Get payment history for an invoice

Operation: get_payment_history

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Invoice ID

Responses

200 Payment history retrieved

DataResponse_PaymentHistory

data*: object — Payment history response

pagination: any

404 Invoice not found

500 Internal server error

GET /billing/payment-methods

GET /billing/payment-methods List payment methods for the organization

Operation: list_payment_methods

Responses

200 Payment methods retrieved

DataResponse_Vec_PaymentMethod

data*: array

pagination: any

500 Internal server error

POST /billing/payment-methods

POST /billing/payment-methods Add a payment method for the organization

Operation: add_payment_method

Request Body (required)

AddPaymentMethodRequest

set_as_default*: boolean

stripe_payment_method_id*: string

Responses

200 Payment method added

DataResponse_PaymentMethodAdded

data*: object — Response for adding a payment method

pagination: any

400 Invalid request

500 Internal server error

DELETE /billing/payment-methods/{id}

DELETE /billing/payment-methods/{id} Remove a payment method from the organization

Operation: delete_payment_method

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Payment method ID

Responses

204 Payment method removed

404 Payment method not found

500 Internal server error

GET /payments/supported

GET /payments/supported Returns supported x402 payment kinds for facilitator discovery.

Operation: get_supported

Responses

200 Supported payment kinds

SupportedResponse

extensions: array,null — List of supported extensions

kinds*: array — List of supported payment kinds

signers: any — Signer addresses by network family

500 Internal server error

Plans

Subscription plans and quota management

GET /organizations/{organization_id}/plan

GET /organizations/:org_id/plan Get the current plan for an organization

Operation: get_organization_plan

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 Organization plan retrieved successfully

DataResponse_OrganizationPlanWithDetails

data*: object — Response type that includes both the plan and organization_plan details

pagination: any

404 Organization or plan not found

500 Internal server error

POST /organizations/{organization_id}/plan

POST /organizations/:org_id/plan Upgrade or downgrade an organization's plan

Operation: change_organization_plan

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Request Body (required)

ChangePlanRequest

plan_id*: string

stripe_payment_method_id: any

Responses

200 Plan changed successfully

DataResponse_OrganizationPlanWithDetails

data*: object — Response type that includes both the plan and organization_plan details

pagination: any

400 Invalid request

404 Organization or plan not found

500 Internal server error

GET /organizations/{organization_id}/quota

GET /organizations/:org_id/quota Get current quota usage for an organization

Operation: get_quota_usage

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 Quota usage retrieved successfully

DataResponse_QuotaUsage

data*: object — Quota usage summary for an organization

pagination: any

404 Organization or plan not found

500 Internal server error

GET /plans

GET /plans List all available subscription plans

Operation: list_plans

Responses

200 Plans retrieved successfully

DataResponse_Vec_Plan

data*: array

pagination: any

500 Internal server error

GET /plans/{plan_id}

GET /plans/:plan_id Get details of a specific plan

Operation: get_plan

Parameters

Name	In	Type	Required	Description
`plan_id`	path	string	Yes	Plan ID

Responses

200 Plan retrieved successfully

DataResponse_Plan

data*: object — Plan represents a subscription tier (Free, Launch, Scale)

pagination: any

404 Plan not found

500 Internal server error

Audit Logs

Audit trail and activity logging

GET /organizations/{organization_id}/audit-logs

List audit logs for an organization

Operation: list_audit_logs

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`actor_id`	query	string,null	No	Filter by actor ID
`action`	query	string,null	No	Filter by action (e.g., "project.create")
`resource_type`	query	string,null	No	Filter by resource type (e.g., "project", "branch")
`resource_id`	query	string,null	No	Filter by resource ID
`status`	query	string,null	No	Filter by status
`action_category`	query	string,null	No	Filter by action category
`start_date`	query	string,null	No	Filter by start date (ISO 8601)
`end_date`	query	string,null	No	Filter by end date (ISO 8601)
`limit`	query	integer	No	Maximum number of results (default 50, max 100)
`offset`	query	integer	No	Offset for pagination

Responses

200 Audit logs retrieved successfully

DataResponse_AuditLogList

data*: object — Response for listing audit logs

pagination: any

401 Unauthorized

403 Forbidden - not a member of this organization

404 Organization not found

GET /organizations/{organization_id}/audit-logs/{log_id}

Get a specific audit log entry

Operation: get_audit_log

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`log_id`	path	string	Yes	Audit log ID

Responses

200 Audit log retrieved successfully

DataResponse_AuditLog

data*: object — Audit log entry from the database

pagination: any

401 Unauthorized

403 Forbidden - not a member of this organization

404 Audit log not found

RBAC

Role-based access control and permissions

PUT /organizations/{organization_id}/members/{member_id}/role

Assign a role to an organization member

Operation: assign_role

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`member_id`	path	string	Yes	Member user ID

Request Body (required)

AssignRoleRequest

role_id: string,null — Either role_id or role_name must be provided

role_name: string,null — Name of the role (owner, admin, editor, viewer, or custom role name)

Responses

200 Role assigned successfully

400 Invalid request

401 Unauthorized

403 Forbidden - requires org.manage_members permission

404 Member or role not found

GET /organizations/{organization_id}/permissions/check/{permission}

Check if the current user has a specific permission

Operation: check_permission

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`permission`	path	string	Yes	Permission name to check

Responses

200 Permission check result

401 Unauthorized

403 Forbidden - not a member of this organization

GET /organizations/{organization_id}/permissions/mine

Get current user's permissions in an organization

Operation: get_my_permissions

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 User's permissions

Array<string>

401 Unauthorized

403 Forbidden - not a member of this organization

GET /organizations/{organization_id}/roles

List roles for an organization (includes built-in roles)

Operation: list_organization_roles

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 Roles retrieved successfully

DataResponse_Vec_RbacRole

data*: array

pagination: any

401 Unauthorized

403 Forbidden - not a member of this organization

POST /organizations/{organization_id}/roles

Create a custom role

Operation: create_organization_role

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Request Body (required)

CreateRoleRequest

description: string,null

name*: string

permissions*: array

Responses

201 Role created successfully

DataResponse_RbacRole

data*: object — Response after creating or updating a role

pagination: any

400 Invalid request

401 Unauthorized

403 Forbidden - requires org.manage_roles permission

GET /organizations/{organization_id}/roles/{role_id}

Get a specific role

Operation: get_role

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`role_id`	path	string	Yes	Role ID

Responses

200 Role retrieved successfully

DataResponse_RbacRole

data*: object — Response after creating or updating a role

pagination: any

401 Unauthorized

403 Forbidden - not a member of this organization

404 Role not found

DELETE /organizations/{organization_id}/roles/{role_id}

Delete a custom role

Operation: delete_organization_role

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`role_id`	path	string	Yes	Role ID

Responses

204 Role deleted successfully

400 Cannot delete built-in role

401 Unauthorized

403 Forbidden - requires org.manage_roles permission

404 Role not found

PATCH /organizations/{organization_id}/roles/{role_id}

Update a custom role

Operation: update_role

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`role_id`	path	string	Yes	Role ID

Request Body (required)

UpdateRoleRequest

description: string,null

permissions: array,null

Responses

200 Role updated successfully

DataResponse_RbacRole

data*: object — Response after creating or updating a role

pagination: any

400 Invalid request or cannot modify built-in role

401 Unauthorized

403 Forbidden - requires org.manage_roles permission

404 Role not found

GET /permissions

List all permissions

Operation: list_permissions

Responses

200 Permissions retrieved successfully

Array<

Permission

action*: string

created_at*: string

description: string,null

id*: string

name*: string

resource_type*: string

>

401 Unauthorized

Webhooks

Webhook configuration and delivery management

GET /organizations/{organization_id}/webhooks

List webhooks for an organization

Operation: list_webhooks

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Responses

200 Webhooks retrieved successfully

DataResponse_Vec_WebhookInfo

data*: array

pagination: any

401 Unauthorized

403 Forbidden - not a member of this organization

POST /organizations/{organization_id}/webhooks

Create a webhook

Operation: create_webhook

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization

Request Body (required)

CreateWebhookRequest

events*: array

name*: string

project_id: string,null

url*: string

Responses

201 Webhook created successfully

DataResponse_WebhookCreated

data*: object — Webhook created response (includes secret on creation only)

pagination: any

400 Invalid request

401 Unauthorized

403 Forbidden - not a member of this organization

GET /organizations/{organization_id}/webhooks/{webhook_id}

Get a specific webhook

Operation: get_webhook

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`webhook_id`	path	string	Yes	Webhook ID

Responses

200 Webhook retrieved successfully

DataResponse_WebhookInfo

data*: object — Webhook response (hides secret)

pagination: any

401 Unauthorized

403 Forbidden - not a member of this organization

404 Webhook not found

DELETE /organizations/{organization_id}/webhooks/{webhook_id}

Delete a webhook

Operation: delete_webhook

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`webhook_id`	path	string	Yes	Webhook ID

Responses

204 Webhook deleted successfully

401 Unauthorized

403 Forbidden - not a member of this organization

404 Webhook not found

PATCH /organizations/{organization_id}/webhooks/{webhook_id}

Update a webhook

Operation: update_webhook

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`webhook_id`	path	string	Yes	Webhook ID

Request Body (required)

UpdateWebhookRequest

enabled: boolean,null

events: array,null

url: string,null

Responses

200 Webhook updated successfully

DataResponse_WebhookInfo

data*: object — Webhook response (hides secret)

pagination: any

400 Invalid request

401 Unauthorized

403 Forbidden - not a member of this organization

404 Webhook not found

GET /organizations/{organization_id}/webhooks/{webhook_id}/deliveries

List recent deliveries for a webhook

Operation: list_webhook_deliveries

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`webhook_id`	path	string	Yes	Webhook ID

Responses

200 Deliveries retrieved successfully

Array<

WebhookDelivery

attempt_number*: integer

created_at*: string

delivered_at: string,null

error_message: string,null

event_id*: string

event_type*: string

id*: string

next_retry_at: string,null

payload*: object

response_body: string,null

... and 2 more properties

>

401 Unauthorized

403 Forbidden - not a member of this organization

404 Webhook not found

POST /organizations/{organization_id}/webhooks/{webhook_id}/rotate-secret

Regenerate webhook secret

Operation: rotate_webhook_secret

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`webhook_id`	path	string	Yes	Webhook ID

Responses

200 Secret rotated successfully

DataResponse_WebhookCreated

data*: object — Webhook created response (includes secret on creation only)

pagination: any

401 Unauthorized

403 Forbidden - not a member of this organization

404 Webhook not found

GET /webhooks/event-types

List available event types

Operation: list_event_types

Responses

200 Event types retrieved successfully

Array<string>

401 Unauthorized

Sessions

User session management

GET /sessions

List all active sessions for the current user

Operation: list_sessions

Responses

200 Sessions retrieved successfully

Array<

Session

created_at*: string

expires_at*: string

id*: string

ip_address: string,null

is_current*: boolean

last_active_at*: string

user_agent: string,null

>

401 Unauthorized

POST /sessions/revoke-all

Revoke all sessions (logout everywhere)

Operation: revoke_all_sessions

Responses

200 All sessions revoked successfully

DataResponse_SessionsRevoked

data*: object

pagination: any

401 Unauthorized

DELETE /sessions/{session_id}

Revoke a specific session

Operation: revoke_session

Parameters

Name	In	Type	Required	Description
`session_id`	path	string	Yes	Session ID to revoke

Responses

200 Session revoked successfully

DataResponse_SessionsRevoked

data*: object

pagination: any

401 Unauthorized

404 Session not found

POST /sessions/{session_id}/revoke-others

Revoke all sessions except a specified one

Operation: revoke_other_sessions

Parameters

Name	In	Type	Required	Description
`session_id`	path	string	Yes	Session ID to keep (current session)

Responses

200 Other sessions revoked successfully

DataResponse_SessionsRevoked

data*: object

pagination: any

401 Unauthorized

404 Session not found or doesn't belong to user

agent-wallet

Wallet (funded + promotional)

GET /wallet/balance

Get wallet balance (funded + promotional)

Operation: get_wallet_balance

Responses

200 Wallet balance retrieved

WalletBalanceDataResponse

data*: WalletBalanceResponse

401 Unauthorized

POST /wallet/bonus/payment-method

Claim payment method bonus (if not already claimed)

Operation: claim_payment_method_bonus

Responses

200 Payment method bonus claimed

BonusClaimDataResponse

data*: BonusClaimResponse

401 Unauthorized

403 Recovery setup required

409 Bonus already claimed

POST /wallet/bonus/signup

Claim signup bonus (if not already claimed)

Operation: claim_signup_bonus

Responses

200 Signup bonus claimed

BonusClaimDataResponse

data*: BonusClaimResponse

401 Unauthorized

403 Recovery setup required

409 Bonus already claimed

POST /wallet/daily/claim

Claim daily free credits

Operation: claim_daily

Responses

200 Daily credits claimed

DailyClaimDataResponse

data*: DailyClaimResponse

400 Not eligible for daily claim

401 Unauthorized

403 Recovery setup required

GET /wallet/daily/eligibility

Check if user can claim daily credits

Operation: check_daily_eligibility

Responses

200 Eligibility checked

DailyClaimEligibilityDataResponse

data*: DailyClaimEligibilityResponse

401 Unauthorized

POST /wallet/deposit

Deposit funds via Stripe

Operation: create_deposit

Request Body (required)

DepositRequest

amount_cents*: integer — Amount in USD cents (minimum 500 = $5.00)

referral_code: string,null — Optional affiliate referral code for tracking

Responses

200 Deposit initiated

DepositDataResponse

data*: DepositResponse

400 Invalid request

401 Unauthorized

403 Recovery setup required

POST /wallet/deposit/crypto

Deposit configured asset via on-chain payment flow

Allows agents to deposit the configured asset directly on-chain to their prepaid balance.
Follows the 402 payment protocol:
1. First request (no payment header) returns 402 with payment requirements
2. Second request (with payment header) settles on-chain and credits balance

Operation: onchain_deposit

Request Body (required)

OnchainDepositRequest

amount*: string — Amount to deposit in the configured asset (decimal string, e.g., "10.50")

asset_id: string,null — Optional asset id to deposit (defaults to publisher primary asset)

publisher_id*: string — Publisher to deposit funds for

Responses

200 Deposit successful

OnchainDepositResponse

agent_wallet*: WalletAddress — Agent wallet address

asset_symbol*: string — Asset symbol (e.g., USDC, USDT)

balance_amount*: string — New balance (configured asset)

deposited_amount*: string — Amount deposited (configured asset)

message*: string — Deposit successful message

publisher_id*: string — Publisher ID

tx_hash: string,null — On-chain transaction hash

400 Invalid request

402 Payment required

PaymentRequiredResponseWithInfo

any

404 Publisher not found

500 Internal server error

POST /wallet/recover

POST /wallet/recover Recover an agent account using a recovery code.

This endpoint allows agents who have lost their API key to recover their account
using the recovery code they saved when setting up wallet recovery.

**What this does:**
- Verifies the recovery code
- Revokes all existing API keys (for security)
- Issues a new API key
- Rotates the recovery code (old code is invalidated)

**Important:** Save both the new API key AND the new recovery code - they're only shown once!

Operation: wallet_recover

Request Body (required)

WalletRecoverRequest

recovery_code*: string — Recovery code (24 characters). Dashes/whitespace are allowed; letters are case-i

Responses

200 Account recovered successfully

WalletRecoverDataResponse

data*: WalletRecoverResponse

400 Invalid request

401 Invalid recovery code

500 Internal server error

POST /wallet/recovery

Set up account recovery (recovery code and/or email).

- If you don't have a `recovery_code` yet, this endpoint generates one and returns it **once**.
- If you already have a `recovery_code`, it will not be shown again.
- You can optionally set/update a recovery `email` for human account recovery.

Use the recovery code with `POST /wallet/recover` to rotate access after losing your API key.

Operation: set_recovery

Request Body (required)

SetRecoveryRequest

email: string,null — Email address for account recovery (optional, for human contact)

Responses

200 Recovery set up

RecoveryDataResponse

data*: RecoveryResponse

401 Unauthorized

GET /wallet/referral

Get user's referral info and code

Operation: get_referral_info

Responses

200 Referral info retrieved

ReferralInfoDataResponse

data*: ReferralInfoResponse

401 Unauthorized

POST /wallet/referral/apply

Apply a referral code to the current user

Operation: apply_referral_code

Request Body (required)

ApplyReferralRequest

referral_code*: string

Responses

200 Referral code applied

400 Invalid referral code

401 Unauthorized

409 Already has a referrer

GET /wallet/transactions

Get transaction history including credits and debits

Operation: get_transactions

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	No	Maximum number of transactions to return (default 50, max 100)
`offset`	query	integer	No	Offset for pagination
`include_usage`	query	boolean	No	Include raw usage/micropayment debits (default false). When false, usage debits are aggregated by day and publisher.
`start_date`	query	string,null	No	Filter: only transactions on or after this date (YYYY-MM-DD, interpreted as UTC midnight)
`end_date`	query	string,null	No	Filter: only transactions strictly before this date (YYYY-MM-DD, interpreted as UTC midnight). To include a full day, set end_date to the day after the last day you want.

Responses

200 Transaction history retrieved

WalletTransactionHistoryDataResponse

data*: WalletTransactionHistoryResponse

401 Unauthorized

GET /wallet/transactions/export

Export transactions as a CSV file for a date range

Operation: export_transactions

Parameters

Name	In	Type	Required	Description
`start_date`	query	string,null	No	Start date (YYYY-MM-DD, inclusive, UTC midnight)
`end_date`	query	string,null	No	End date (YYYY-MM-DD, exclusive, UTC midnight)

Responses

200 CSV file download

401 Unauthorized

GET /wallet/transactions/summary

Get summary statistics for transactions in a date range

Operation: get_transaction_summary

Parameters

Name	In	Type	Required	Description
`start_date`	query	string,null	No	Start date (YYYY-MM-DD, inclusive, UTC midnight)
`end_date`	query	string,null	No	End date (YYYY-MM-DD, exclusive, UTC midnight)

Responses

200 Transaction summary retrieved

TransactionSummaryDataResponse

data*: TransactionSummaryResponse

401 Unauthorized

publisher-payments

Publisher payment APIs for first-class services

POST /billing/publishers/{slug}/charges

POST /billing/publishers/{slug}/charges

Operation: create_charge

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug

Request Body (required)

CreateChargeRequest

agent_wallet*: string

amount_atomic*: integer

description*: string

idempotency_key: string,null

Responses

200 Charge created

DataResponse_PublisherChargeInfo

data*: object

pagination: any

401 Unauthorized

402 Insufficient balance

403 Forbidden

404 Publisher not found

GET /billing/publishers/{slug}/charges/{charge_id}

GET /billing/publishers/{slug}/charges/{charge_id}

Operation: get_charge_status

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug
`charge_id`	path	string	Yes	Charge ID

Responses

200 Charge retrieved

DataResponse_PublisherChargeInfo

data*: object

pagination: any

401 Unauthorized

403 Forbidden

404 Charge not found

POST /billing/publishers/{slug}/charges/{charge_id}/refund

POST /billing/publishers/{slug}/charges/{charge_id}/refund

Operation: refund_charge

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug
`charge_id`	path	string	Yes	Charge ID

Request Body (required)

RefundChargeRequest

reason*: string

Responses

200 Charge refunded

DataResponse_PublisherChargeInfo

data*: object

pagination: any

401 Unauthorized

403 Forbidden

404 Charge not found

POST /billing/publishers/{slug}/charges/{charge_id}/slash

POST /billing/publishers/{slug}/charges/{charge_id}/slash

Operation: slash_charge

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug
`charge_id`	path	string	Yes	Original charge ID

Request Body (required)

SlashChargeRequest

reason*: string

slash_amount_atomic*: integer

Responses

204 Slash applied

401 Unauthorized

402 Insufficient balance

403 Forbidden

404 Charge not found

POST /billing/publishers/{slug}/payouts

POST /billing/publishers/{slug}/payouts

Operation: create_payout

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug

Request Body (required)

CreatePayoutRequest

amount_atomic*: integer

description*: string

destination_wallet*: string

idempotency_key: string,null

Responses

200 Payout created

DataResponse_PublisherPayoutInfo

data*: object

pagination: any

401 Unauthorized

403 Forbidden

404 Publisher not found

GET /billing/publishers/{slug}/payouts/{payout_id}

GET /billing/publishers/{slug}/payouts/{payout_id}

Operation: get_payout_status

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug
`payout_id`	path	string	Yes	Payout ID

Responses

200 Payout retrieved

DataResponse_PublisherPayoutInfo

data*: object

pagination: any

401 Unauthorized

403 Forbidden

404 Payout not found

GET /wallet/lookup/{agent_wallet}

GET /wallet/lookup/{agent_wallet} Look up an agent's available balance (for publisher pre-checks)

Operation: get_agent_balance

Parameters

Name	In	Type	Required	Description
`agent_wallet`	path	string	Yes	Agent wallet address

Responses

200 Balance retrieved

DataResponse_PublisherAgentBalance

data*: object

pagination: any

401 Unauthorized

403 Forbidden

404 Publisher not found

publishers

Unified publisher proxy API

GET /publishers

GET /publishers List publishers with full details and pricing (store view)

Operation: list_store_publishers

Parameters

Name	In	Type	Required	Description
`is_verified`	query	boolean,null	No	Filter by verification status
`category`	query	string	No	Filter by publisher category
`search`	query	string,null	No	Search by name or slug
`limit`	query	integer	No	Maximum number of results (default: 50, max: 100)
`offset`	query	integer	No	Offset for pagination

Responses

200 Publishers retrieved successfully

PaginatedResponse_Vec_PublisherResponse

data*: array

pagination*: OffsetPaginationMeta — Pagination metadata

400 Invalid query parameters

500 Internal server error

GET /publishers/suggest

GET /publishers/suggest Suggest publishers based on a task or query

Operation: suggest_publishers

Parameters

Name	In	Type	Required	Description
`query`	query	string	Yes	The task or query to match against publisher capabilities. Examples: "scrape website", "AI research", "PDF extraction"
`type`	query	string	No	Type of suggestions: "publisher", "agent", or "both" (default: "both") Note: Agent suggestions are planned but not yet implemented.
`limit`	query	integer	No	Maximum number of results (default: 5, max: 20)

Responses

200 Publisher suggestions retrieved successfully

DataResponse_SuggestResponse

data*: object — Response for suggest endpoint Returns publisher and agent recommendations based

pagination: any

400 Invalid query parameters

500 Internal server error

GET /publishers/{slug}

GET /publishers/{slug} Get publisher by slug (store view with full details)

Operation: get_store_publisher

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug

Responses

200 Publisher retrieved successfully

DataResponse_PublisherResponse

data*: object — Publisher response (excludes sensitive fields)

pagination: any

404 Publisher not found

500 Internal server error

POST /publishers/{slug}

Handle requests to the publisher root.

For database publishers, this executes a query from the request body.
For API publishers, this proxies to the root endpoint.
For agent publishers (compute_type=agent), this creates a task and returns 202 Accepted.
For MCP publishers, this returns an error (use specific tool/resource endpoints).

Operation: publisher_root_handler

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug identifier

Request Body (required)

PublisherRootRequest

oneOf: [

DatabaseQueryRequest

database: string,null — Optional database name (primarily for SerenDB publishers)

params: array — Query parameters

query*: string — Query payload to execute. - SQL publishers (serendb/neon/supabase): SQL string

| any]

Responses

200 Request processed successfully (database/API)

any

202 Agent task accepted (async)

any

402 Payment required

404 Publisher not found

500 Internal server error

POST /publishers/{slug}/estimate

Estimate query cost without payment

Operation: estimate_query

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug

Request Body (required)

EstimateRequestBody

asset_id: string,null — Optional asset id to estimate pricing for (defaults to publisher primary asset)

publisher_id*: string — Publisher UUID

query*: string — Query payload to estimate. - SQL publishers (serendb/neon/supabase): SQL string

Responses

200 Cost estimate

EstimateResponse

asset_symbol*: string — Asset symbol (e.g., USDC, USDT)

estimated_cost*: string — Estimated cost in configured asset

estimated_cost_atomic*: integer — Estimated cost in atomic units

estimated_rows*: integer — Estimated rows to be returned

publisher_name*: string — Publisher name

publisher_slug*: string — Publisher slug

404 Publisher not found

500 Internal server error

GET /publishers/{slug}/logo

GET /publishers/{slug}/logo Fetch publisher logo (inline data or redirect to URL) Accepts either publisher slug or UUID for backwards compatibility

Operation: get_store_publisher_logo

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug or UUID

Responses

200 Publisher logo bytes

302 Redirect to external logo URL

404 Logo not found

GET /publishers/{slug}/{path}

Operation: proxy_to_publisher_get

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug identifier
`path`	path	string	Yes	Path to proxy to the publisher

Responses

200 Request proxied successfully

any

402 Payment required

403 Publisher is geo-restricted and routing is not enabled

GeoRestrictedError

error*: string

message*: string

opt_in_endpoint*: string

proxy_region*: string

publisher*: string

404 Publisher or endpoint not found

500 Internal server error

POST /publishers/{slug}/{path}

Operation: proxy_to_publisher_post

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Publisher slug identifier
`path`	path	string	Yes	Path to proxy to the publisher

Responses

200 Request proxied successfully

any

402 Payment required

403 Publisher is geo-restricted and routing is not enabled

GeoRestrictedError

error*: string

message*: string

opt_in_endpoint*: string

proxy_region*: string

publisher*: string

404 Publisher or endpoint not found

500 Internal server error

Eval

Eval signal ingestion and routing matrix

GET /eval/matrix

Get the global eval routing matrix.

Operation: get_matrix

Responses

200 Eval matrix

EvalMatrixResponse

generated_at*: string

matrix*: object

total_signals*: integer

401 Unauthorized

POST /eval/signals

Ingest eval signals from Seren Desktop clients.

Operation: post_signals

Request Body (required)

EvalSignalRequest

signals*: array

Responses

201 Signals accepted

EvalSignalResponse

accepted*: integer

rejected*: integer

400 Invalid request

401 Unauthorized

federation

Cross-publisher resource discovery and federation

GET /federation

GET /federation List federated resources with optional filtering. Used for cross-publisher resource discovery.

Operation: list_resources

Parameters

Name	In	Type	Required	Description
`publisher_slug`	query	string,null	No	Filter by publisher slug
`resource_type`	query	string,null	No	Filter by resource type (e.g., "bounty", "dataset")
`status`	query	string,null	No	Filter by status (default: "active")
`limit`	query	integer	No	Maximum number of results (default: 50, max: 100)
`offset`	query	integer	No	Offset for pagination

Responses

200 Resources retrieved successfully

DataResponse_Vec_FederatedResourceWithPublisherResponse

data*: array

pagination: any

400 Invalid query parameters

500 Internal server error

POST /federation

POST /federation Upsert a federated resource for a publisher. Publishers use this to register/update their resources for cross-publisher discovery.

Operation: upsert_resource

Request Body (required)

UpsertFederatedResourceRequest

expires_at: string,null — Optional expiration timestamp

external_id*: string — External ID of the resource (unique within publisher + type)

metadata*: any — Resource metadata (JSON object with type-specific fields)

org_database_id: string,null — Optional database ID where the resource data lives

publisher_slug: string,null — Optional publisher slug for disambiguation when an organization owns multiple pu

resource_type*: string — Type of resource being registered

status: string — Resource status (default: "active")

Responses

200 Resource upserted successfully

DataResponse_FederatedResourceResponse

data*: object — Response for a single federated resource

pagination: any

400 Invalid request

401 Authentication required

403 Not authorized - must be a publisher

500 Internal server error

GET /federation/history

GET /federation/history List append-only federation history events.

Operation: list_history

Parameters

Name	In	Type	Required	Description
`publisher_slug`	query	string,null	No	Filter by publisher slug
`resource_type`	query	string,null	No	Filter by resource type
`external_id`	query	string,null	No	Filter by external resource ID
`operation`	query	string,null	No	Filter by history operation: insert, update, delete
`limit`	query	integer	No	Maximum number of results (default: 50, max: 100)
`offset`	query	integer	No	Offset for pagination

Responses

200 History retrieved successfully

DataResponse_Vec_FederatedResourceHistoryResponse

data*: array

pagination: any

400 Invalid query parameters

500 Internal server error

GET /federation/history/stats

GET /federation/history/stats Get aggregate statistics over federation history.

Operation: get_history_stats

Parameters

Name	In	Type	Required	Description
`publisher_slug`	query	string,null	No	Filter by publisher slug (optional)
`resource_type`	query	string,null	No	Filter by resource type (optional)

Responses

200 History stats retrieved successfully

DataResponse_FederationHistoryStatsResponse

data*: object — Response for federation history aggregate statistics.

pagination: any

500 Internal server error

GET /federation/stats

GET /federation/stats Get federation statistics, optionally filtered by publisher.

Operation: get_stats

Parameters

Name	In	Type	Required	Description
`publisher_slug`	query	string,null	No	Filter by publisher slug (optional - if omitted, returns stats across all publishers)

Responses

200 Stats retrieved successfully

DataResponse_FederationStatsResponse

data*: object — Response for federation statistics

pagination: any

500 Internal server error

GET /federation/{id}

GET /federation/{id} Get a specific federated resource by ID.

Operation: get_resource

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Federated resource ID

Responses

200 Resource retrieved successfully

DataResponse_FederatedResourceResponse

data*: object — Response for a single federated resource

pagination: any

404 Resource not found

500 Internal server error

DELETE /federation/{resource_type}/{external_id}

DELETE /federation/{resource_type}/{external_id} Delete a federated resource by type and external ID. Only the owning publisher can delete their resources.

Operation: delete_resource

Parameters

Name	In	Type	Required	Description
`resource_type`	path	string	Yes	Resource type
`external_id`	path	string	Yes	External resource ID

Responses

204 Resource deleted successfully

401 Authentication required

403 Not authorized to delete this resource

404 Resource not found

500 Internal server error

Agent Tasks

GET /organizations/{organization_id}/agents/tasks

GET /organizations/{organization_id}/agents/tasks

Operation: list_tasks

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID
`limit`	query	integer	No
`offset`	query	integer	No

Responses

200 Tasks retrieved

DataResponse_Vec_AgentTask

data*: array

pagination: any

403 Not authorized

GET /organizations/{organization_id}/agents/tasks/{task_id}

GET /organizations/{organization_id}/agents/tasks/{task_id}

Operation: get_task

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID
`task_id`	path	string	Yes	Task ID

Responses

200 Task retrieved

DataResponse_AgentTask

data*: object — An agent task — tracks a single agent invocation lifecycle.

pagination: any

404 Task not found

POST /organizations/{organization_id}/agents/tasks/{task_id}/cancel

POST /organizations/{organization_id}/agents/tasks/{task_id}/cancel

Operation: cancel_task

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID
`task_id`	path	string	Yes	Task ID

Responses

200 Task canceled

DataResponse_AgentTask

data*: object — An agent task — tracks a single agent invocation lifecycle.

pagination: any

400 Already terminal

404 Not found

GET /organizations/{organization_id}/agents/tasks/{task_id}/events

GET /organizations/{organization_id}/agents/tasks/{task_id}/events

Operation: list_task_events

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID
`task_id`	path	string	Yes	Task ID

Responses

200 Events retrieved

DataResponse_Vec_AgentTaskEvent

data*: array

pagination: any

404 Not found

GET /organizations/{organization_id}/agents/tasks/{task_id}/stream

GET /organizations/{organization_id}/agents/tasks/{task_id}/stream

Operation: stream_task

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID
`task_id`	path	string	Yes	Task ID

Responses

200 SSE event stream

Agent Analytics

GET /organizations/{organization_id}/publishers/{publisher_id}/analytics/revenue

GET /organizations/:org_id/publishers/:publisher_id/analytics/revenue Get revenue metrics with period-over-period comparison.

Operation: get_revenue_metrics

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID
`days`	query	integer	No	Number of days to analyze (default: 30)

Responses

200 Revenue metrics

RevenueMetrics

active_agents*: integer — Number of active agents in the period

agents_change_pct*: integer — Agent count change from previous period (percentage)

avg_query_cost_atomic*: integer — Average query cost (atomic units)

period_end*: string — Period end date (ISO 8601)

period_start*: string — Period start date (ISO 8601)

queries_change_pct*: integer — Query count change from previous period (percentage)

revenue_change_pct*: integer — Revenue change from previous period (percentage, e.g., 15 = +15%)

total_queries*: integer — Total queries executed in the period

total_revenue*: string — Total revenue as decimal string

total_revenue_atomic*: integer — Total revenue in the period (atomic units)

401 Unauthorized

404 Publisher not found

GET /organizations/{organization_id}/publishers/{publisher_id}/analytics/revenue-by-day

GET /organizations/:org_id/publishers/:publisher_id/analytics/revenue-by-day Get daily revenue breakdown.

Operation: get_revenue_by_day

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID
`days`	query	integer	No	Number of days to analyze (default: 30)

Responses

200 Daily revenue breakdown

Array<

RevenueByDay

date*: string — Date (YYYY-MM-DD)

query_count*: integer — Number of queries on this day

revenue*: string — Revenue as decimal string

revenue_atomic*: integer — Revenue on this day (atomic units)

unique_agents*: integer — Number of unique agents on this day

>

401 Unauthorized

404 Publisher not found

GET /organizations/{organization_id}/publishers/{publisher_id}/analytics/top-agents

GET /organizations/:org_id/publishers/:publisher_id/analytics/top-agents Get top agents by spending.

Operation: get_top_agents

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID
`limit`	query	integer	No	Number of agents to return (default: 10)

Responses

200 Top agents by spending

Array<

TopAgent

agent_wallet*: string — Agent wallet address

balance_atomic*: integer — Current balance (atomic units)

last_active: string,null — Last activity timestamp (ISO 8601)

query_count*: integer — Number of queries executed

rank*: integer — Rank (1 = highest spender)

total_spent*: string — Total amount spent as decimal string

total_spent_atomic*: integer — Total amount spent (atomic units)

>

401 Unauthorized

404 Publisher not found

templates

GET /organizations/{organization_id}/templates/analytics/{publisher_id}

GET /organizations/{organization_id}/templates/analytics/{publisher_id} Get template analytics for a specific publisher

Operation: get_publisher_template_analytics

Parameters

Name	In	Type	Required	Description
`organization_id`	path	string	Yes	Organization ID or 'default' for authenticated user's default organization
`publisher_id`	path	string	Yes	Publisher ID

Responses

200 Analytics retrieved successfully

DataResponse_PublisherAnalytics

data*: object — Response for publisher analytics

pagination: any

401 Unauthorized

403 Not authorized

404 Publisher not found

500 Internal server error

GET /templates

GET /templates List available templates in the catalog

Operation: list_templates

Parameters

Name	In	Type	Required	Description
`verified_only`	query	boolean	No	Filter to verified templates only
`language`	query	string	No	Filter by language (python, typescript, javascript)
`min_price`	query	integer	No	Minimum price in atomic units
`max_price`	query	integer	No	Maximum price in atomic units
`search`	query	string	No	Search in name and description
`sort_by`	query	string	No	Sort order (popularity, price_asc, price_desc, newest, oldest)
`limit`	query	integer	No	Maximum number of templates to return (default: 50)
`offset`	query	integer	No	Offset for pagination (default: 0)

Responses

200 Templates retrieved successfully

DataResponse_Vec_AgentTemplateSummary

data*: array

pagination: any

500 Internal server error

POST /templates/publish

POST /templates/publish Publish a new agent template

Operation: publish_template

Request Body (required)

CreateTemplateRequest

code*: string — Template source code implementing run(input) -> output

computeBackend: string,null — Preferred compute backend (e.g., "daytona", "modal"). If not specified, uses def

dependencies: array,null — Package dependencies (e.g., ["requests", "openai"])

description: string,null — Description of what the template does

language*: TemplateLanguage — Programming language (python, typescript, javascript)

llmConfig: any

name*: string — Display name

price*: string — Price per invocation (e.g., "0.05" for $0.05)

settingsSchema: array,null — Publisher-defined user-configurable settings schema

slug*: string — URL-friendly slug (unique identifier)

Responses

201 Template published successfully

DataResponse_CreateTemplateResponse

data*: object — Response after creating a template

pagination: any

400 Invalid request

401 Authentication required

409 Template slug already exists

500 Internal server error

GET /templates/{slug}

GET /templates/{slug} Get template details by slug

Operation: get_template

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Template slug

Responses

200 Template retrieved successfully

DataResponse_CreateTemplateResponse

data*: object — Response after creating a template

pagination: any

404 Template not found

500 Internal server error

POST /templates/{slug}/invoke

POST /templates/{slug}/invoke Invoke an agent template.

Supports two modes:
- **Bearer auth present**: uses the authenticated user's SerenBucks balance.
- **No bearer auth**: uses x402 (requires `X-AGENT-WALLET` + payment headers).

Operation: invoke_template

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	Template slug

Request Body (required)

InvokeTemplateRequest

input*: any — Input data to pass to the template

Responses

200 Template invoked successfully

DataResponse_InvokeTemplateResponse

data*: object — Response from invoking a template

pagination: any

400 Invalid request

401 Authentication failed

402 Payment required

404 Template not found

500 Internal server error

503 Sandbox execution failed

webhooks

POST /webhooks/stripe

POST /webhooks/stripe Handle Stripe webhook events

Operation: handle_stripe_webhook

Responses

200 Webhook processed

400 Invalid webhook signature

500 Internal server error