DataResponse_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. # 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 |
object | Yes | Publisher response (excludes sensitive fields) |
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.\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": "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",
"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"
},
"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"
}
]
}
}
}