DataResponse_Vec_PublisherResponse
Generic API response wrapper with optional pagination This wrapper provides a consistent structure for all API responses, making it easier for clients to handle responses uniformly. It supports both single resources and collections, with optional pagination metadata. Publisher endpoints use the same wrapper for non-streaming JSON success responses, including first-class publishers. Streaming endpoints such as SSE responses carry metering in response headers and are not wrapped. Payment-required and error responses are also not wrapped so clients can parse their existing wire contracts directly. # Response Structure ```json { "data": T, "pagination": { ... } // optional } ``` # Examples ## Single Resource ```rust use seren_core::http::DataResponse; use serde::Serialize; #[derive(Serialize)] struct Project { id: String, name: String, } let project = Project { id: "123".to_string(), name: "My Project".to_string(), }; let response = DataResponse::new(project); // Serializes to: {"data": {"id": "123", "name": "My Project"}} ``` ## Collection with Pagination ```rust use seren_core::http::DataResponse; use seren_core::pagination::PaginationMeta; use serde::Serialize; #[derive(Serialize)] struct Project { id: String, name: String, } let projects: Vec<Project> = Vec::new(); let pagination = PaginationMeta { total: 0, count: 0, limit: 20, offset: 0, has_more: false, }; let response = DataResponse::with_pagination(projects, pagination); // Serializes to: {"data": [...], "pagination": {"total": 0, "count": 0, "limit": 20, "offset": 0, "has_more": false}} ```
Properties
| Property | Type | Required | Description |
|---|---|---|---|
data |
Array<object> | Yes | |
pagination |
any | No |
View JSON Schema
{
"type": "object",
"description": "Generic API response wrapper with optional pagination\n\nThis wrapper provides a consistent structure for all API responses,\nmaking it easier for clients to handle responses uniformly. It supports\nboth single resources and collections, with optional pagination metadata.\nPublisher endpoints use the same wrapper for non-streaming JSON success\nresponses, including first-class publishers. Streaming endpoints such as\nSSE responses carry metering in response headers and are not wrapped.\nPayment-required and error responses are also not wrapped so clients can\nparse their existing wire contracts directly.\n\n# Response Structure\n\n```json\n{\n \"data\": T,\n \"pagination\": { ... } // optional\n}\n```\n\n# Examples\n\n## Single Resource\n\n```rust\nuse seren_core::http::DataResponse;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet project = Project {\n id: \"123\".to_string(),\n name: \"My Project\".to_string(),\n};\n\nlet response = DataResponse::new(project);\n// Serializes to: {\"data\": {\"id\": \"123\", \"name\": \"My Project\"}}\n```\n\n## Collection with Pagination\n\n```rust\nuse seren_core::http::DataResponse;\nuse seren_core::pagination::PaginationMeta;\nuse serde::Serialize;\n\n#[derive(Serialize)]\nstruct Project {\n id: String,\n name: String,\n}\n\nlet projects: Vec<Project> = Vec::new();\nlet pagination = PaginationMeta {\n total: 0,\n count: 0,\n limit: 20,\n offset: 0,\n has_more: false,\n};\n\nlet response = DataResponse::with_pagination(projects, pagination);\n// Serializes to: {\"data\": [...], \"pagination\": {\"total\": 0, \"count\": 0, \"limit\": 20, \"offset\": 0, \"has_more\": false}}\n```",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"description": "Publisher response (excludes sensitive fields)",
"required": [
"id",
"name",
"slug",
"categories",
"capabilities",
"use_cases",
"publisher_type",
"wallet_address",
"wallet_network_id",
"publisher_category",
"billing_model",
"gateway_fee_percent",
"allowed_passthrough_headers",
"request_content_type",
"upstream_headers",
"ownership_tracking_enabled",
"undocumented_endpoint_policy",
"is_active",
"is_verified",
"total_queries",
"unique_agents_served",
"total_revenue_atomic",
"created_at",
"updated_at",
"requires_user_oauth"
],
"properties": {
"a2a_agent_card": {
"description": "Cached A2A agent card"
},
"a2a_endpoint_url": {
"type": [
"string",
"null"
],
"description": "A2A endpoint base URL (for compute_type = agent)"
},
"a2a_health_status": {
"type": [
"string",
"null"
],
"description": "A2A health status: unknown, healthy, unhealthy, unreachable"
},
"accepted_assets": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/AssetInfo"
},
"description": "Accepted assets for payment"
},
"allowed_passthrough_headers": {
"type": "array",
"items": {
"type": "string"
}
},
"api_key_header": {
"type": [
"string",
"null"
],
"description": "Header name to inject upstream_api_key into (e.g., \"Authorization\", \"X-API-Key\")"
},
"api_key_query_param": {
"type": [
"string",
"null"
],
"description": "Query parameter name to inject upstream_api_key into (e.g., \"api_key\", \"apiKey\")"
},
"api_url": {
"type": [
"string",
"null"
],
"description": "External API URL (for integration_type = api)"
},
"billing_model": {
"type": "string"
},
"branch_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "SerenDB branch ID (for database_type = serendb)"
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Publisher-declared capabilities for task matching"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"compute_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ComputeType",
"description": "Compute type when publisher_category = compute"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"database_config": {
"description": "Provider config (sensitive fields redacted)"
},
"database_name": {
"type": [
"string",
"null"
],
"description": "Database name within the SerenDB project"
},
"database_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DatabaseType",
"description": "Database type when publisher_category = database"
}
]
},
"description": {
"type": [
"string",
"null"
]
},
"email": {
"type": [
"string",
"null"
],
"description": "Publisher contact email for notifications and support"
},
"endpoints": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/EndpointDefinition"
},
"description": "Structured endpoint definitions for LLM discoverability and access control"
},
"gateway_fee_percent": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"integration_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/IntegrationType",
"description": "Integration type when publisher_category = integration"
}
]
},
"is_active": {
"type": "boolean"
},
"is_verified": {
"type": "boolean"
},
"logo_url": {
"type": [
"string",
"null"
]
},
"mcp_capabilities": {
"description": "Cached MCP capabilities (tools, resources, prompts)"
},
"mcp_endpoint": {
"type": [
"string",
"null"
],
"description": "MCP server endpoint URL (for integration_type = mcp)"
},
"name": {
"type": "string"
},
"oauth_provider_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "OAuth provider ID for BYOC (Bring Your Own Credentials) authentication"
},
"ownership_tracking_enabled": {
"type": "boolean"
},
"pricing": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/PricingConfigResponse"
},
"description": "Pricing config per asset (if included)"
},
"project_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "SerenDB project ID (for database_type = serendb)"
},
"protected_operations": {},
"publisher_category": {
"$ref": "#/components/schemas/PublisherCategory",
"description": "Publisher category: database, integration, or compute"
},
"publisher_type": {
"$ref": "#/components/schemas/PublisherType"
},
"request_content_type": {
"type": "string",
"description": "Content-Type for upstream API requests"
},
"requires_user_oauth": {
"type": "boolean",
"description": "If true, users must connect via OAuth before using this publisher"
},
"resource_description": {
"type": [
"string",
"null"
]
},
"resource_id_response_path": {
"type": [
"string",
"null"
]
},
"resource_id_url_pattern": {
"type": [
"string",
"null"
]
},
"resource_name": {
"type": [
"string",
"null"
]
},
"routing": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/GeoRoutingConfig",
"description": "Geographic routing configuration (if publisher has geo-restricted upstream API)"
}
]
},
"slug": {
"type": "string"
},
"token_cache_ttl_seconds": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "TTL for cached exchanged tokens in seconds"
},
"token_exchange_method": {
"type": [
"string",
"null"
],
"description": "HTTP method for exchange endpoint (POST or GET)"
},
"token_exchange_mode": {
"type": [
"string",
"null"
],
"description": "How to send Seren token: header, body, or query"
},
"token_exchange_url": {
"type": [
"string",
"null"
],
"description": "URL to call for exchanging Seren API keys for publisher auth tokens"
},
"token_response_field": {
"type": [
"string",
"null"
],
"description": "JSON field in exchange response containing the token"
},
"total_queries": {
"type": "integer",
"format": "int64"
},
"total_revenue_atomic": {
"type": "integer",
"format": "int64",
"description": "Lifetime total revenue across all assets, in atomic units"
},
"undocumented_endpoint_policy": {
"$ref": "#/components/schemas/UndocumentedEndpointPolicy",
"description": "Policy for handling requests to paths not in the endpoints catalog"
},
"unique_agents_served": {
"type": "integer",
"format": "int64"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"upstream_cost_response_path": {
"type": [
"string",
"null"
],
"description": "Dot-separated path to upstream cost in response body (for pay_per_use and prepaid passthrough billing).\nExample: \"usage.cost\""
},
"upstream_headers": {
"description": "Non-sensitive headers to send to upstream API"
},
"usage_examples": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/UsageExample"
},
"description": "Usage examples showing how to call the publisher's API"
},
"use_cases": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable use case descriptions"
},
"verification_expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When verification expires (NULL = no expiry)"
},
"wallet_address": {
"$ref": "#/components/schemas/WalletAddress"
},
"wallet_network_id": {
"type": "string",
"description": "Network for the wallet address"
}
}
}
},
"pagination": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/PaginationMeta",
"description": "Optional pagination metadata"
}
]
}
}
}