{ "openapi": "3.1.0", "info": { "title": "TC-S Personal Agent and Resident SI API", "version": "1.1.0", "description": "Scoped REST, stateless MCP Streamable HTTP, and A2A 0.3 JSON-RPC for operating networks. Resident tasks provide guidance and engine-link artifacts, not external engine execution. Publication and Solar movement require human approval. No commissioning or launch authority." }, "servers": [ { "url": "https://tcs-commission-network.replit.app/api" } ], "paths": { "/agent/mcp": { "post": { "operationId": "callMcpAgent", "description": "Stateless Streamable HTTP JSON-RPC MCP transport. Requires a human-scoped agent Bearer token. Tools are filtered by delegation scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRpcEnvelope" } } } }, "responses": { "200": { "description": "MCP JSON-RPC response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "204": { "description": "Notification accepted" } }, "security": [ { "AgentDelegation": [] } ] } }, "/agent/a2a": { "post": { "operationId": "sendA2aMessage", "description": "A2A 0.3 JSON-RPC message/send and tasks/get. Requires resident:run scope. Non-streaming, synchronous bounded resident tasks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRpcEnvelope" } } } }, "responses": { "200": { "description": "A2A task or JSON-RPC error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "AgentDelegation": [] } ] } }, "/agent/.well-known/agent-card.json": { "get": { "operationId": "getResidentAgentCard", "responses": { "200": { "description": "Public generic discovery; no private network or member data", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [] } }, "/agent/me": { "get": { "operationId": "agentGetIdentity", "security": [ { "AgentDelegation": [] } ], "responses": { "200": { "description": "Delegated human identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentIdentity" } } } } } } }, "/agent/network": { "get": { "operationId": "agentGetNetwork", "security": [ { "AgentDelegation": [] } ], "responses": { "200": { "description": "Single delegated network", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Network" } } } } } } }, "/agent/listings": { "get": { "operationId": "agentListListings", "security": [ { "AgentDelegation": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } }, { "name": "category", "in": "query", "schema": { "type": "string", "maxLength": 60 } }, { "name": "creator", "in": "query", "description": "Case-insensitive seller name or exact seller member ID", "schema": { "type": "string", "maxLength": 120 } }, { "name": "featured", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Authorized marketplace listings", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } } } } } } } }, "/agent/wallets": { "get": { "operationId": "agentListWallets", "security": [ { "AgentDelegation": [] } ], "responses": { "200": { "description": "Delegator wallet only", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } } } } } }, "/agent/library": { "get": { "operationId": "agentListLibrary", "security": [ { "AgentDelegation": [] } ], "responses": { "200": { "description": "Delegator library metadata only", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryItem" } } } } } } } }, "/agent/requests": { "get": { "operationId": "agentListRequests", "security": [ { "AgentDelegation": [] } ], "responses": { "200": { "description": "This connection's proposals", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRequest" } } } } } } }, "post": { "operationId": "agentSubmitRequest", "security": [ { "AgentDelegation": [] } ], "description": "Propose only. No financial or listing side effects before human approval. Requests expire after 24 hours.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProposalInput" } } } }, "responses": { "201": { "description": "Immutable proposal with server-computed economics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRequest" } } } } } } }, "/agent/requests/{requestId}": { "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "agentGetRequest", "security": [ { "AgentDelegation": [] } ], "responses": { "200": { "description": "This connection's request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRequest" } } } } } } } }, "components": { "schemas": { "AgentRpcEnvelope": { "type": "object", "additionalProperties": false, "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "number", "null" ] }, "method": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } } }, "AgentIdentity": { "type": "object", "required": [ "connection", "networkId", "memberId", "scopes" ], "properties": { "connection": { "$ref": "#/components/schemas/AgentConnection" }, "networkId": { "type": "string" }, "memberId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "AgentConnection": { "type": "object", "required": [ "id", "networkId", "name", "scopes", "createdAt", "expiresAt", "revokedAt", "lastUsedAt" ], "properties": { "id": { "type": "string" }, "networkId": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ] }, "lastUsedAt": { "type": [ "string", "null" ] } } }, "Network": { "type": "object", "required": [ "id", "networkId", "slug", "config", "status", "createdAt", "updatedAt", "isQa", "ownerId", "paymentStatus", "commercialApproved", "error", "role" ], "properties": { "id": { "type": "string" }, "networkId": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "config": { "$ref": "#/components/schemas/NetworkConfig" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "commissionedAt": { "type": [ "string", "null" ] }, "launchedAt": { "type": [ "string", "null" ] }, "isQa": { "type": "boolean" }, "ownerId": { "type": "string" }, "paymentStatus": { "type": "string" }, "commercialApproved": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "order": { "$ref": "#/components/schemas/CommissioningOrder" }, "membershipOrder": { "$ref": "#/components/schemas/MembershipOrder" } } }, "NetworkConfig": { "type": "object", "required": [ "organizationName", "name", "networkType", "memberLimit", "agentLimit", "visibility", "solarEnabled", "dailyIssuanceEnabled", "dailyIssuanceRays", "marketplaceEnabled", "sellerMode", "primaryColor", "secondaryColor", "description", "welcomeMessage", "heroMessage", "logoUrl", "categories", "genesisRays", "transactionFeeBps", "reserveBps", "raysEnabled", "agentsEnabled", "agentMarketplaceEnabled", "humanOriginatorRequired", "agentCreationPermission", "governance", "launchTiming", "digitalAssetsEnabled", "servicesEnabled", "physicalFulfillmentEnabled", "ticketedEventEnabled", "ticketAllowanceRays" ], "properties": { "organizationName": { "type": "string", "maxLength": 120 }, "name": { "type": "string", "maxLength": 120 }, "networkType": { "type": "string" }, "memberLimit": { "type": "integer", "minimum": 1, "maximum": 100000 }, "agentLimit": { "type": "integer", "minimum": 0, "maximum": 100 }, "visibility": { "type": "string", "enum": [ "private", "public" ] }, "solarEnabled": { "type": "boolean" }, "dailyIssuanceEnabled": { "type": "boolean" }, "dailyIssuanceRays": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "marketplaceEnabled": { "type": "boolean" }, "sellerMode": { "type": "string", "enum": [ "commissioner", "approved", "open" ] }, "memberAgentProxyEnabled": { "type": "boolean", "default": false, "description": "Allow members to create and use personal-agent delegations. Commissioner delegations remain allowed." }, "paidTopoffsEnabled": { "type": "boolean", "default": false, "description": "Commissioner opt-in for future paid Solar top-offs. Pricing and checkout are not configured; this does not enable payments or issuance." }, "pricingMode": { "type": "string", "enum": [ "ai_guided", "fixed_category" ] }, "fixedCategoryPricesRays": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "description": "Fixed exact listing price in Rays for each configured category when pricingMode is fixed_category." }, "primaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "description": { "type": "string", "maxLength": 2000 }, "welcomeMessage": { "type": "string", "maxLength": 1000 }, "heroMessage": { "type": "string", "maxLength": 200 }, "logoUrl": { "type": "string", "maxLength": 500 }, "categories": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 60 } }, "genesisRays": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "transactionFeeBps": { "type": "integer", "minimum": 0, "maximum": 1000 }, "reserveBps": { "type": "integer", "minimum": 0, "maximum": 1000 }, "raysEnabled": { "type": "boolean" }, "agentsEnabled": { "type": "boolean" }, "agentMarketplaceEnabled": { "type": "boolean" }, "humanOriginatorRequired": { "type": "boolean" }, "agentCreationPermission": { "type": "string", "enum": [ "commissioner", "members" ] }, "governance": { "type": "string", "maxLength": 4000 }, "launchTiming": { "type": "string", "maxLength": 120 }, "eventStartDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional local calendar start date for an event; legacy events without a date remain manually managed." }, "eventDurationDays": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Number of local calendar days, including the start date. Event-only." }, "eventTimezone": { "type": "string", "maxLength": 100, "description": "IANA timezone used to determine the final local event day." }, "eventOrdersPaused": { "type": "boolean", "description": "Commissioner stops accepting new event purchase orders when service or transaction completion is unavailable; does not end the event." }, "digitalAssetsEnabled": { "type": "boolean" }, "servicesEnabled": { "type": "boolean" }, "physicalFulfillmentEnabled": { "type": "boolean" }, "ticketedEventEnabled": { "type": "boolean", "default": false, "description": "Opt into paid-roster access controls. Disabled by default to preserve legacy network behavior." }, "ticketAllowanceRays": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "default": 10000, "description": "One-time independently denominated Solar Rays allowance for each claimed paid ticket; never derived from USD." } } }, "CommissioningOrder": { "type": "object", "required": [ "networkId", "packageKey", "setupUsd", "depositUsd", "balanceUsd", "monthlyUsd", "acceptedBy", "acceptedAt", "checkouts" ], "properties": { "networkId": { "type": "string" }, "packageKey": { "type": "string", "enum": [ "pilot", "production", "growth", "enterprise" ] }, "setupUsd": { "type": "integer" }, "depositUsd": { "type": "integer" }, "balanceUsd": { "type": "integer" }, "monthlyUsd": { "type": "integer" }, "acceptedBy": { "type": "string" }, "acceptedAt": { "type": "string" }, "checkouts": { "type": "object", "properties": { "deposit": { "$ref": "#/components/schemas/CommissioningCheckout" }, "balance": { "$ref": "#/components/schemas/CommissioningCheckout" }, "monthly": { "$ref": "#/components/schemas/CommissioningCheckout" } } } } }, "CommissioningCheckout": { "type": "object", "required": [ "id", "url" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "paymentId": { "type": "string" }, "paidAt": { "type": "string" } } }, "MembershipOrder": { "type": "object", "required": [ "networkId", "quote", "acceptedBy", "acceptedAt", "checkouts" ], "properties": { "networkId": { "type": "string" }, "quote": { "$ref": "#/components/schemas/MembershipQuote" }, "acceptedBy": { "type": "string" }, "acceptedAt": { "type": "string", "format": "date-time" }, "checkouts": { "type": "object", "properties": { "deposit": { "$ref": "#/components/schemas/CommissioningCheckout" }, "balance": { "$ref": "#/components/schemas/CommissioningCheckout" } } }, "settlement": { "$ref": "#/components/schemas/MembershipSettlement" }, "disposition": { "$ref": "#/components/schemas/MembershipRequest" }, "cancellation": { "$ref": "#/components/schemas/MembershipRequest" } } }, "MembershipQuote": { "type": "object", "required": [ "version", "projectedUsers", "projectedUsd", "depositUsd", "monthlyUsd", "currency" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "projectedUsers": { "type": "integer", "minimum": 100 }, "projectedUsd": { "type": "integer" }, "depositUsd": { "type": "number" }, "monthlyUsd": { "type": "integer", "enum": [ 0 ] }, "currency": { "type": "string", "enum": [ "USD" ] } } }, "MembershipSettlement": { "type": "object", "required": [ "version", "actualUsers", "finalUsd", "paidVerifiedUsd", "balanceUsd", "unusedUsd", "finalizedAt" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "actualUsers": { "type": "integer" }, "finalUsd": { "type": "integer" }, "paidVerifiedUsd": { "type": "number" }, "balanceUsd": { "type": "number" }, "unusedUsd": { "type": "number" }, "finalizedAt": { "type": "string", "format": "date-time" } } }, "MembershipRequest": { "type": "object", "required": [ "kind", "choice", "amountUsd", "status", "requestedAt", "requestedBy", "reason" ], "properties": { "kind": { "type": "string", "enum": [ "disposition", "cancellation" ] }, "choice": { "type": "string", "enum": [ "refund", "donation" ] }, "amountUsd": { "type": "number" }, "status": { "type": "string", "enum": [ "requested", "provider_completed" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "requestedBy": { "type": "string" }, "reason": { "type": "string" }, "recipient": { "type": "string" }, "providerCompletedAt": { "type": "string", "format": "date-time" } } }, "Listing": { "allOf": [ { "$ref": "#/components/schemas/ListingInput" }, { "type": "object", "required": [ "id", "networkId", "sellerId", "sellerName", "createdAt", "featured", "stockSold", "stockTotal", "perMemberLimit" ], "properties": { "featured": { "type": "boolean" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileAsset" } }, "id": { "type": "string" }, "networkId": { "type": "string" }, "sellerId": { "type": "string" }, "sellerName": { "type": "string" }, "createdAt": { "type": "string" }, "stockSold": { "type": "integer", "minimum": 0, "description": "Number of completed sales; server-managed and read-only." } } } ] }, "ListingInput": { "type": "object", "required": [ "title", "description", "category", "priceRays", "kind", "active" ], "properties": { "fileIds": { "type": "array", "maxItems": 30, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "maxLength": 4000 }, "category": { "type": "string", "maxLength": 60 }, "priceRays": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "kind": { "type": "string", "enum": [ "digital", "service", "physical", "voucher" ] }, "artifactPurpose": { "type": "string", "enum": [ "informational", "inference", "media", "3d", "bundle" ], "description": "Digital artifact intent; defaults to informational. Inference files are data", "never executed.": null }, "voucherType": { "type": "string", "enum": [ "food", "service" ], "description": "Required for voucher; food needs physical fulfillment enabled", "service needs services enabled.": null }, "voucherTerms": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Required for voucher; must specify the exact item or service entitlement and how to redeem it." }, "active": { "type": "boolean" }, "stockTotal": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Finite inventory total; null means unlimited. In ticketed events only digital listings may be unlimited." }, "perMemberLimit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional maximum purchases of this listing per buyer." }, "analysisReceipt": { "type": "string", "maxLength": 1024, "description": "Short-lived signed LifeLens analysis attestation; never persisted." } } }, "FileAsset": { "type": "object", "required": [ "id", "name", "contentType", "size", "createdAt" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "integer" }, "createdAt": { "type": "string" } } }, "Wallet": { "type": "object", "required": [ "id", "networkId", "memberId", "memberName", "balanceRays", "type" ], "properties": { "id": { "type": "string" }, "networkId": { "type": "string" }, "memberId": { "type": [ "string", "null" ] }, "memberName": { "type": "string" }, "balanceRays": { "type": "integer" }, "type": { "type": "string" } } }, "LibraryItem": { "type": "object", "required": [ "id", "fileId", "name", "contentType", "size", "createdAt", "source", "listingTitle", "canShare" ], "properties": { "id": { "type": "string" }, "fileId": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "integer" }, "createdAt": { "type": "string" }, "source": { "type": "string", "enum": [ "uploaded", "purchased", "received" ] }, "listingTitle": { "type": [ "string", "null" ] }, "canShare": { "type": "boolean" } } }, "AgentRequest": { "type": "object", "required": [ "id", "connectionId", "connectionName", "networkId", "action", "payload", "status", "createdAt", "decidedAt", "error", "result" ], "properties": { "id": { "type": "string" }, "connectionId": { "type": "string" }, "connectionName": { "type": "string" }, "networkId": { "type": "string" }, "action": { "type": "string", "enum": [ "createListing", "purchase", "transfer" ] }, "payload": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "pending", "completed", "rejected", "failed" ] }, "createdAt": { "type": "string" }, "decidedAt": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "result": { "type": [ "object", "null" ], "additionalProperties": true } } }, "AgentProposalInput": { "type": "object", "additionalProperties": false, "required": [ "action", "payload", "idempotencyKey" ], "properties": { "action": { "type": "string", "enum": [ "createListing", "purchase", "transfer" ] }, "payload": { "type": "object", "additionalProperties": true, "description": "createListing: ListingInput. purchase: {listingId}. transfer: {toMemberId,amountRays,description?}. Actor identity, economics and action idempotency are server-owned." }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 100 } } } }, "securitySchemes": { "AgentDelegation": { "type": "http", "scheme": "bearer", "description": "Human-created TC-S delegation token; never send in URLs. resident:run explicitly permits AI-credit use." } } } }