{ "openapi": "3.1.0", "info": { "title": "Oriva Platform API", "version": "1.0.0", "description": "Public API for 3rd party Oriva developers. Authenticate with your API key as a Bearer token." }, "servers": [ { "url": "https://api.oriva.io", "description": "Production" }, { "url": "http://localhost:3002", "description": "Local BFF proxy" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "API key with oriva_pk_ prefix" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "UserMe": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "username": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "bio": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ], "format": "uri" }, "avatar": { "type": [ "string", "null" ], "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "apiKeyInfo": { "type": "object", "properties": { "keyId": { "type": "string" }, "name": { "type": "string" }, "userId": { "type": "string", "format": "uuid" }, "permissions": { "type": "array", "items": { "type": "string" } }, "usageCount": { "type": "integer" } }, "required": [ "keyId", "name", "userId", "permissions", "usageCount" ] } }, "required": [ "id", "username", "displayName", "email", "bio", "location", "website", "avatar", "createdAt", "updatedAt", "apiKeyInfo" ] } }, "required": [ "ok", "success", "data" ] }, "AnalyticsSummary": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "overview": { "type": "object", "properties": { "totalEntries": { "type": "integer" }, "totalResponses": { "type": "integer" }, "totalGroups": { "type": "integer" }, "installedApps": { "type": "integer" } }, "required": [ "totalEntries", "totalResponses", "totalGroups", "installedApps" ] }, "metrics": { "type": "object", "properties": { "entriesGrowth": { "type": "string" }, "responseGrowth": { "type": "string" }, "groupActivity": { "type": "string" }, "appUsage": { "type": "string" } }, "required": [ "entriesGrowth", "responseGrowth", "groupActivity", "appUsage" ] }, "recentActivity": { "type": "array", "items": {} }, "timeRange": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } }, "required": [ "start", "end" ] } }, "required": [ "overview", "metrics", "recentActivity", "timeRange" ] }, "message": { "type": "string" } }, "required": [ "ok", "success", "data" ] }, "ProfileSummary": { "type": "object", "properties": { "profileId": { "type": "string", "example": "ext_a1b2c3d4e5f6a7b8" }, "profileName": { "type": "string" }, "isActive": { "type": "boolean" }, "avatar": { "type": [ "string", "null" ], "format": "uri" }, "isDefault": { "type": "boolean" } }, "required": [ "profileId", "profileName", "isActive", "avatar", "isDefault" ] }, "UpdatedProfile": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "profileId": { "type": "string" }, "profileName": { "type": "string" }, "isActive": { "type": "boolean" }, "avatar": { "type": [ "string", "null" ], "format": "uri" }, "bio": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "profileId", "profileName", "isActive", "avatar", "bio", "location", "updatedAt" ] }, "message": { "type": "string" } }, "required": [ "ok", "success", "data" ] }, "GroupSummary": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid" }, "groupName": { "type": "string" }, "memberCount": { "type": "integer" }, "isActive": { "type": "boolean" }, "role": { "type": "string", "example": "admin" }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ], "format": "uri" }, "external_link": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "groupId", "groupName", "memberCount", "isActive", "role", "description", "image_url", "external_link" ] }, "GroupMember": { "type": "object", "properties": { "memberId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "joinedAt": { "type": "string", "format": "date-time" }, "avatar": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "memberId", "displayName", "role", "joinedAt", "avatar" ] }, "AuthSessionResponse": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "subscription_tier": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "email", "display_name", "username", "subscription_tier", "created_at" ] }, "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "integer" } }, "required": [ "user", "access_token", "refresh_token", "expires_in" ] }, "AuthProfileResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": [ "string", "null" ], "format": "email" }, "displayName": { "type": "string" }, "avatar": { "type": [ "string", "null" ], "format": "uri" }, "authType": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "lastLogin": { "type": "string", "format": "date-time" }, "accountStatus": { "type": "string" }, "twoFactorEnabled": { "type": "boolean" }, "emailVerified": { "type": "boolean" } }, "required": [ "id", "email", "displayName", "avatar", "authType", "permissions", "lastLogin", "accountStatus", "twoFactorEnabled", "emailVerified" ] } }, "required": [ "ok", "success", "data" ] }, "RawProfileResponse": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "bio": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" }, "location": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "display_name", "username", "bio", "avatar_url", "location", "website_url" ] }, "TokenRefreshResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "integer" } }, "required": [ "access_token", "refresh_token", "expires_in" ] }, "TeamMember": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "displayName": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri" }, "role": { "type": "string" }, "joinedAt": { "type": "string", "format": "date-time" }, "group": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "profileId", "displayName", "username", "avatarUrl", "role", "joinedAt", "group" ] }, "MarketplaceApp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "icon_url": { "type": [ "string", "null" ], "format": "uri" }, "screenshots": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uri" } }, "version": { "type": "string" }, "pricing_model": { "type": "string" }, "pricing_config": { "type": [ "object", "null" ], "additionalProperties": {} }, "install_count": { "type": "integer" }, "developer_id": { "type": "string", "format": "uuid" }, "developer_name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_review", "approved", "rejected" ] }, "is_active": { "type": "boolean" }, "supported_audience": { "type": [ "array", "null" ], "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "category", "version", "pricing_model", "install_count", "developer_id", "developer_name", "status", "is_active", "created_at", "updated_at" ] }, "InstalledApp": { "type": "object", "properties": { "installationId": { "type": "string", "format": "uuid" }, "installedAt": { "type": "string", "format": "date-time" }, "isActive": { "type": "boolean" }, "settings": { "type": [ "object", "null" ], "additionalProperties": {} }, "app": { "$ref": "#/components/schemas/MarketplaceApp" } }, "required": [ "installationId", "installedAt", "isActive", "settings", "app" ] }, "MarketplaceItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "profile_id": { "type": "string", "format": "uuid" }, "entry_type": { "type": "string" }, "marketplace_metadata": { "type": [ "object", "null" ], "additionalProperties": {} }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "profile_id", "entry_type", "created_at", "updated_at" ] }, "Category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "collection_type": { "type": "string" }, "organization_rules": { "type": [ "object", "null" ], "additionalProperties": {} }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "collection_type", "created_at", "updated_at" ] }, "Entry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "content": { "type": "string" }, "profile_id": { "type": "string", "format": "uuid" }, "audience_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "content", "profile_id", "audience_type", "created_at", "updated_at" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "location": { "type": [ "string", "null" ] }, "isOnline": { "type": "boolean" }, "category": { "type": "string" }, "organizer": { "type": "string", "format": "uuid" }, "maxAttendees": { "type": [ "integer", "null" ] }, "currentAttendees": { "type": [ "integer", "null" ] }, "price": { "type": "number", "minimum": 0 }, "tags": { "type": "array", "items": { "type": "string" } }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "description", "startDate", "endDate", "location", "isOnline", "category", "organizer", "maxAttendees", "currentAttendees", "price", "tags", "imageUrl", "createdAt", "updatedAt" ] }, "CreatedPersonalToken": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "Full token value — displayed ONCE. Store it now; it cannot be retrieved again." }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "First 20 characters of the token, safe to display later." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "token", "id", "name", "prefix", "created_at", "expires_at" ] } }, "required": [ "ok", "success", "data" ] }, "PersonalTokenSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_active": { "type": "boolean" } }, "required": [ "id", "name", "prefix", "created_at", "last_used_at", "expires_at", "is_active" ] }, "PersonalTokenList": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalTokenSummary" } } }, "required": [ "ok", "success", "data" ] }, "PaymentLink": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Stripe Checkout Session ID (cs_…)." }, "url": { "type": "string", "description": "Hosted Checkout URL. Redirect the buyer here." }, "expires_at": { "type": "integer", "description": "Unix timestamp (seconds) when the Checkout Session expires." } }, "required": [ "id", "url", "expires_at" ] } }, "required": [ "ok", "success", "data" ] }, "CreateBridgeConnectionBody": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "monday", "clickup", "asana", "notion" ], "example": "monday" }, "apiToken": { "type": "string", "minLength": 1, "description": "A personal/API token for the external tool (headless connect)." } }, "required": [ "platform", "apiToken" ] }, "TriggerBridgeSyncBody": { "type": "object", "properties": { "bridgeGroupId": { "type": "string", "format": "uuid" } }, "required": [ "bridgeGroupId" ] }, "BridgeConnection": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "monday", "clickup", "asana", "notion" ], "example": "monday" }, "connected": { "type": "boolean" }, "workspaceId": { "type": [ "string", "null" ] }, "connectedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "platform", "connected", "workspaceId", "connectedAt" ] }, "BridgeGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "participantCount": { "type": "integer" }, "health": { "type": [ "string", "null" ], "example": "healthy" } }, "required": [ "id", "name", "description", "participantCount", "health" ] }, "BridgeTask": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bridgeGroupId": { "type": "string", "format": "uuid" }, "sourcePlatform": { "type": "string" }, "sourceId": { "type": "string" }, "title": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "dueDate": { "type": [ "string", "null" ] } }, "required": [ "id", "bridgeGroupId", "sourcePlatform", "sourceId", "title", "status", "priority", "dueDate" ] }, "AgentError": { "type": "object", "properties": { "error": { "type": "string", "description": "What went wrong, in plain words." } }, "required": [ "error" ] }, "BuyListingBody": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "description": "The marketplace listing (entry) id to buy." }, "expectedAmountCents": { "type": "integer", "minimum": 1, "description": "The exact current total you agreed to pay, in cents (1200 = 12.00). If the listing price differs, the purchase is refused before any charge." }, "variantIndex": { "type": "integer", "description": "Which of the listing's price variants to buy (0-based). Omit for the default." } }, "required": [ "listingId", "expectedAmountCents" ] }, "AgentPurchaseBought": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent purchase id." }, "orderId": { "type": "string", "description": "Marketplace order id." }, "orderNumber": { "type": [ "string", "null" ], "description": "Human-readable order number." }, "amountCents": { "type": "integer", "description": "Amount charged, in cents." }, "currency": { "type": "string", "description": "ISO 4217 currency code." } }, "required": [ "id", "orderId", "orderNumber", "amountCents", "currency" ] } }, "required": [ "purchase" ] }, "AgentPurchaseRepeat": { "type": "object", "properties": { "repeat": { "type": "boolean", "enum": [ true ] }, "purchase": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "description": "Status of the earlier attempt with this Idempotency-Key." } }, "required": [ "id", "status" ] }, "message": { "type": "string" } }, "required": [ "repeat", "purchase", "message" ] }, "AgentPurchasePending": { "type": "object", "properties": { "pending": { "type": "boolean", "enum": [ true ] }, "purchase": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": [ "string", "null" ] } }, "required": [ "id", "orderId" ] }, "message": { "type": "string" } }, "required": [ "pending", "purchase", "message" ] }, "AgentPurchaseRefused": { "type": "object", "properties": { "error": { "type": "string", "description": "Why the purchase was refused." }, "refused": { "type": "boolean", "enum": [ true ] }, "purchaseId": { "type": [ "string", "null" ] } }, "required": [ "error", "refused", "purchaseId" ] }, "AgentPurchaseCardFailed": { "type": "object", "properties": { "error": { "type": "string", "description": "The card decline's own message, or \"The card was not charged.\"" }, "purchaseId": { "type": [ "string", "null" ] } }, "required": [ "error", "purchaseId" ] }, "AgentPurchaseRecord": { "type": "object", "properties": { "id": { "type": "string" }, "entry_id": { "type": "string", "description": "The listing that was bought." }, "listing_title": { "type": [ "string", "null" ] }, "order_id": { "type": [ "string", "null" ] }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "description": "pending, succeeded, failed or refused." }, "reason": { "type": [ "string", "null" ], "description": "Why it was refused or failed, when it was." }, "created_at": { "type": "string" } }, "required": [ "id", "entry_id", "listing_title", "order_id", "amount_cents", "currency", "status", "reason", "created_at" ] }, "AgentPurchaseList": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPurchaseRecord" } } }, "required": [ "purchases" ] }, "CreateListingBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Listing title, up to 200 characters." }, "description": { "type": "string", "maxLength": 20000, "description": "What is being sold, up to 20,000 characters. Runs through the content check." }, "price": { "type": "number", "minimum": 0, "maximum": 10000, "description": "Price in currency units (12 = 12.00), 0 to 10000. A paid listing is at least 1." }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Only USD is supported. Defaults to USD." }, "itemType": { "type": "string", "enum": [ "digital", "physical", "service", "course", "app", "event" ], "description": "Kind of item. Defaults to digital." }, "profileId": { "type": "string", "format": "uuid", "description": "One of the owner's named profiles to list under. Defaults to their default profile." }, "publish": { "type": "boolean", "description": "Publish now (default true). Send false to save a draft; publishing a paid listing needs a paid Oriva plan." } }, "required": [ "title", "description", "price" ] }, "AgentListingCreated": { "type": "object", "properties": { "listing": { "type": "object", "properties": { "id": { "type": "string", "description": "The new listing (entry) id." }, "title": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "published": { "type": "boolean" } }, "required": [ "id", "title", "price", "currency", "published" ] } }, "required": [ "listing" ] }, "AgentListingContentRefused": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": [ "string", "null" ] } }, "required": [ "error", "hint" ] } }, "parameters": {} }, "paths": { "/api/v1/user/me": { "get": { "operationId": "getCurrentUser", "tags": [ "User" ], "summary": "Get current user", "description": "Returns the authenticated user's active profile and API key metadata.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMe" } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/analytics/summary": { "get": { "operationId": "getAnalyticsSummary", "tags": [ "Analytics" ], "summary": "Get analytics summary", "description": "Returns 7-day usage analytics for the authenticated API key.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Analytics summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSummary" } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/profiles/available": { "get": { "operationId": "listProfiles", "tags": [ "Profiles" ], "summary": "List available profiles", "description": "Returns all non-anonymous active profiles for the authenticated API key.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Available profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileSummary" } } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/profiles/active": { "get": { "operationId": "getActiveProfile", "tags": [ "Profiles" ], "summary": "Get active profile", "description": "Returns the default active (non-anonymous) profile for the authenticated API key.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Active profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ProfileSummary" } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/profiles/{profileId}": { "put": { "operationId": "updateProfile", "tags": [ "Profiles" ], "summary": "Update a profile", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ext_[a-f0-9]{16}$", "example": "ext_a1b2c3d4e5f6a7b8" }, "required": true, "name": "profileId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "profileName": { "type": "string", "minLength": 1 }, "avatar": { "type": "string", "format": "uri" }, "bio": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatedProfile" } } } }, "400": { "description": "Validation error — invalid profileId format or body" }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/profiles/{profileId}/activate": { "post": { "operationId": "activateProfile", "tags": [ "Profiles" ], "summary": "Activate a profile", "description": "Switches the active profile to the specified profile.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ext_[a-f0-9]{16}$", "example": "ext_a1b2c3d4e5f6a7b8" }, "required": true, "name": "profileId", "in": "path" } ], "responses": { "200": { "description": "Profile activated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "activeProfile": { "type": "string" }, "switchedAt": { "type": "string", "format": "date-time" } }, "required": [ "activeProfile", "switchedAt" ] } }, "required": [ "ok", "success", "data" ] } } } }, "400": { "description": "Validation error — invalid profileId format" }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/groups": { "get": { "operationId": "listGroups", "tags": [ "Groups" ], "summary": "List groups", "description": "Returns all groups the authenticated user created or joined.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "User groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupSummary" } } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/groups/{groupId}/members": { "get": { "operationId": "listGroupMembers", "tags": [ "Groups" ], "summary": "Get group members", "description": "Returns members of a group. Requires the caller to be the creator or a member.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "required": true, "name": "groupId", "in": "path" } ], "responses": { "200": { "description": "Group members", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupMember" } } }, "required": [ "ok", "success", "data" ] } } } }, "400": { "description": "Validation error — invalid groupId format" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Not a member or creator of this group" }, "404": { "description": "Group not found" } } } }, "/api/v1/auth/register": { "post": { "operationId": "register", "tags": [ "Auth" ], "summary": "Register a new user", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8, "pattern": "[A-Z]" }, "name": { "type": "string" }, "username": { "type": "string" }, "preferences": {} }, "required": [ "email", "password" ] } } } }, "responses": { "201": { "description": "User registered and session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } }, "400": { "description": "Validation error — weak password or invalid email" }, "409": { "description": "Email already registered" } } } }, "/api/v1/auth/login": { "post": { "operationId": "login", "tags": [ "Auth" ], "summary": "Log in", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1 } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } }, "400": { "description": "Validation error — missing email or password" }, "401": { "description": "Invalid credentials" } } } }, "/api/v1/auth/logout": { "post": { "operationId": "logout", "tags": [ "Auth" ], "summary": "Log out", "description": "Invalidates the current session. Requires Authorization header.", "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "Logged out" }, "401": { "description": "Missing authorization header" } } } }, "/api/v1/auth/token/refresh": { "post": { "operationId": "refreshToken", "tags": [ "Auth" ], "summary": "Refresh access token", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string", "minLength": 1 } }, "required": [ "refresh_token" ] } } } }, "responses": { "200": { "description": "New tokens issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRefreshResponse" } } } }, "400": { "description": "Validation error — missing refresh_token" }, "401": { "description": "Invalid or expired refresh token" } } } }, "/api/v1/auth/profile": { "get": { "operationId": "getAuthProfile", "tags": [ "Auth" ], "summary": "Get auth profile", "description": "Returns the authenticated user identity and API key metadata.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Auth profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthProfileResponse" } } } }, "401": { "description": "Unauthorized" } } }, "patch": { "operationId": "patchAuthProfile", "tags": [ "Auth" ], "summary": "Update profile (partial)", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "bio": { "type": "string" }, "avatar_url": { "type": "string", "format": "uri" }, "location": { "type": "string" }, "website_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Updated profile row", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RawProfileResponse" } } } }, "400": { "description": "No fields provided" }, "401": { "description": "Unauthorized" } } }, "put": { "operationId": "putAuthProfile", "tags": [ "Auth" ], "summary": "Update profile (full)", "description": "Superset of PATCH — also accepts preferences and data_retention_days (min 30).", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "bio": { "type": "string" }, "avatar_url": { "type": "string", "format": "uri" }, "location": { "type": "string" }, "website_url": { "type": "string", "format": "uri" }, "preferences": { "type": "object", "additionalProperties": {} }, "data_retention_days": { "type": "integer", "minimum": 30 } } } } } }, "responses": { "200": { "description": "Updated profile row", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RawProfileResponse" } } } }, "400": { "description": "No fields provided, or data_retention_days < 30" }, "401": { "description": "Unauthorized" } } } }, "/api/v1/auth/account": { "delete": { "operationId": "deleteAccount", "tags": [ "Auth" ], "summary": "Delete account", "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "Account deleted" }, "401": { "description": "Unauthorized" } } } }, "/api/v1/sessions": { "get": { "operationId": "listSessions", "tags": [ "Sessions" ], "summary": "List sessions", "description": "Returns the user's sessions. Sessions feature is not yet implemented — returns empty paginated list.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Sessions list (currently always empty)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "pagination" ] }, "message": { "type": "string" } }, "required": [ "ok", "success", "data", "meta" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/sessions/upcoming": { "get": { "operationId": "listUpcomingSessions", "tags": [ "Sessions" ], "summary": "List upcoming sessions", "description": "Returns upcoming sessions. Sessions feature is not yet implemented — returns empty list.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Upcoming sessions (currently always empty)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": {} }, "message": { "type": "string" } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/team/members": { "get": { "operationId": "listTeamMembers", "tags": [ "Team" ], "summary": "List team members", "description": "Returns group memberships for the authenticated user as a flat list of team members.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Team members", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "total", "roles" ] } }, "required": [ "ok", "success", "data", "meta" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/marketplace/apps": { "get": { "operationId": "listMarketplaceApps", "tags": [ "Marketplace" ], "summary": "Browse marketplace apps", "description": "Returns paginated list of approved, active marketplace apps.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 0 }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "category", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Marketplace apps", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceApp" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "pagination" ] } }, "required": [ "ok", "success", "data", "meta" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/marketplace/trending": { "get": { "operationId": "listTrendingApps", "tags": [ "Marketplace" ], "summary": "Trending apps", "description": "Returns approved apps sorted by install count (top 20).", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Trending apps", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceApp" } } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/marketplace/featured": { "get": { "operationId": "listFeaturedApps", "tags": [ "Marketplace" ], "summary": "Featured apps", "description": "Returns featured approved apps (curated subset of top apps).", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Featured apps", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceApp" } } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/marketplace/categories": { "get": { "operationId": "listMarketplaceCategories", "tags": [ "Marketplace" ], "summary": "List app categories", "description": "Returns distinct categories from approved apps with their app counts. Note: a second registration of this path exists (no auth, collections-table version) but is shadowed by this route (Express first-match).", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Category counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "category", "count" ] } } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/marketplace/apps/{appId}": { "get": { "operationId": "getMarketplaceApp", "tags": [ "Marketplace" ], "summary": "Get app details", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "appId", "in": "path" } ], "responses": { "200": { "description": "App details", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MarketplaceApp" } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "App not found" } } } }, "/api/v1/marketplace/installed": { "get": { "operationId": "listInstalledApps", "tags": [ "Marketplace" ], "summary": "List installed apps", "description": "Returns all apps installed by the authenticated user.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Installed apps", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledApp" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "pagination" ] } }, "required": [ "ok", "success", "data", "meta" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/v1/marketplace/install/{appId}": { "post": { "operationId": "installMarketplaceApp", "tags": [ "Marketplace" ], "summary": "Install app", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "appId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "additionalProperties": {} } } } } } }, "responses": { "200": { "description": "App installed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/InstalledApp" }, "message": { "type": "string" } }, "required": [ "ok", "success", "data", "message" ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "App not found or not available for installation" }, "409": { "description": "App already installed" } } } }, "/api/v1/marketplace/uninstall/{appId}": { "delete": { "operationId": "uninstallMarketplaceApp", "tags": [ "Marketplace" ], "summary": "Uninstall app", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "appId", "in": "path" } ], "responses": { "200": { "description": "App uninstalled", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "ok", "success", "message" ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "App installation not found" } } } }, "/api/v1/marketplace/items": { "get": { "operationId": "listMarketplaceItems", "tags": [ "Marketplace" ], "summary": "List marketplace items", "description": "Public listing of published marketplace items (entry-based). No authentication required.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 0 }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "item_type", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "earner_type", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "category_id", "in": "query" }, { "schema": { "type": "number" }, "required": false, "name": "min_price", "in": "query" }, { "schema": { "type": "number" }, "required": false, "name": "max_price", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "seller_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Marketplace items", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceItem" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "pagination" ] } }, "required": [ "ok", "success", "data", "meta" ] } } } } } } }, "/api/v1/marketplace/items/{id}": { "get": { "operationId": "getMarketplaceItem", "tags": [ "Marketplace" ], "summary": "Get marketplace item", "description": "Returns a single published marketplace item by ID.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Marketplace item", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MarketplaceItem" } }, "required": [ "ok", "success", "data" ] } } } }, "404": { "description": "Item not found" } } } }, "/api/v1/marketplace/search": { "post": { "operationId": "searchMarketplace", "tags": [ "Marketplace" ], "summary": "Search marketplace", "description": "Full-text search across marketplace items. No authentication required.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "filters": { "type": "object", "additionalProperties": {} }, "limit": { "type": "integer", "maximum": 100 }, "offset": { "type": "integer" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceItem" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "pagination" ] } }, "required": [ "ok", "success", "data", "meta" ] } } } } } } }, "/api/v1/marketplace/categories/tree": { "get": { "operationId": "getCategoryTree", "tags": [ "Marketplace" ], "summary": "Category tree", "description": "Returns marketplace categories as a hierarchical tree from the collections table. Children are nested category objects of the same shape.", "responses": { "200": { "description": "Category tree", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "object", "properties": { "children": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } } } ] } } }, "required": [ "ok", "success", "data" ] } } } } } } }, "/api/v1/marketplace/categories/{id}": { "get": { "operationId": "getMarketplaceCategory", "tags": [ "Marketplace" ], "summary": "Get category", "description": "Returns a single marketplace category from the collections table.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Category", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Category" } }, "required": [ "ok", "success", "data" ] } } } }, "404": { "description": "Category not found" } } } }, "/api/v1/developer/apps": { "get": { "operationId": "listDeveloperApps", "tags": [ "Developer" ], "summary": "List developer apps", "description": "Returns all marketplace apps owned by the authenticated developer.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Developer apps", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceApp" } } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } }, "post": { "operationId": "createDeveloperApp", "tags": [ "Developer" ], "summary": "Create app", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "tagline": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "minLength": 1 }, "icon_url": { "type": "string", "format": "uri" }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" } }, "version": { "type": "string", "default": "1.0.0" }, "pricing_model": { "type": "string", "default": "free" }, "pricing_config": { "type": "object", "additionalProperties": {} }, "supported_audience": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "slug", "category" ] } } } }, "responses": { "201": { "description": "App created (status: draft)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MarketplaceApp" } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/developer/apps/{appId}": { "get": { "operationId": "getDeveloperApp", "tags": [ "Developer" ], "summary": "Get developer app", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "appId", "in": "path" } ], "responses": { "200": { "description": "App details", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MarketplaceApp" } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "App not found or not owned by this developer" } } }, "put": { "operationId": "updateDeveloperApp", "tags": [ "Developer" ], "summary": "Update app", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "appId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "tagline": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "icon_url": { "type": "string", "format": "uri" }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" } }, "version": { "type": "string" }, "pricing_model": { "type": "string" }, "pricing_config": { "type": "object", "additionalProperties": {} }, "supported_audience": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "App updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MarketplaceApp" } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "App not found or not owned by this developer" } } }, "delete": { "operationId": "deleteDeveloperApp", "tags": [ "Developer" ], "summary": "Delete app", "description": "Only draft apps can be deleted. Approved apps must be deactivated first.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "appId", "in": "path" } ], "responses": { "204": { "description": "App deleted" }, "400": { "description": "App is not in draft status — cannot delete" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "App not found or not owned by this developer" } } } }, "/api/v1/developer/apps/{appId}/submit": { "post": { "operationId": "submitDeveloperApp", "tags": [ "Developer" ], "summary": "Submit app for review", "description": "Transitions app from draft → pending_review.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "appId", "in": "path" } ], "responses": { "200": { "description": "App submitted for review", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MarketplaceApp" }, "message": { "type": "string" } }, "required": [ "ok", "success", "data", "message" ] } } } }, "400": { "description": "App is not in draft status" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "App not found or not owned by this developer" } } } }, "/api/v1/developer/apps/{appId}/resubmit": { "post": { "operationId": "resubmitDeveloperApp", "tags": [ "Developer" ], "summary": "Resubmit rejected app", "description": "Updates fields and resubmits a rejected app for review.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "appId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "tagline": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "icon_url": { "type": "string", "format": "uri" }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" } }, "version": { "type": "string" }, "pricing_model": { "type": "string" }, "pricing_config": { "type": "object", "additionalProperties": {} }, "supported_audience": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "App resubmitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MarketplaceApp" }, "message": { "type": "string" } }, "required": [ "ok", "success", "data", "message" ] } } } }, "400": { "description": "App is not in rejected status" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "App not found or not owned by this developer" } } } }, "/api/v1/entries": { "get": { "operationId": "listEntries", "tags": [ "Entries" ], "summary": "List entries", "description": "Returns paginated entries for the authenticated user's profile.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Entries list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "pagination" ] } }, "required": [ "ok", "success", "data", "meta" ] } } } }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "User profile not found" } } } }, "/api/v1/templates": { "get": { "operationId": "listTemplates", "tags": [ "Entries" ], "summary": "List templates", "description": "Returns available entry templates. Not yet implemented — returns empty list.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Templates list (currently always empty)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "pagination" ] } }, "required": [ "ok", "success", "data", "meta" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/storage": { "get": { "operationId": "getStorage", "tags": [ "Entries" ], "summary": "Get storage info", "description": "Returns storage usage for the authenticated user. Not yet implemented — returns empty object.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Storage info", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/ui/notifications": { "post": { "operationId": "createUiNotification", "tags": [ "UI" ], "summary": "Create notification", "description": "Creates a UI notification for the authenticated user.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Notification created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/oriva/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "List events", "description": "Returns active events with optional filtering by category and date range.", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "category", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "startDate", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "endDate", "in": "query" }, { "schema": { "type": "integer", "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Events list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "ok", "success", "data", "total", "limit", "offset" ] } } } } } }, "post": { "operationId": "createEvent", "tags": [ "Events" ], "summary": "Create event", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "isOnline": { "type": "boolean" }, "category": { "type": "string", "minLength": 1 }, "location": { "type": [ "string", "null" ] }, "maxAttendees": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "price": { "type": "number", "minimum": 0 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "title", "description", "startDate", "endDate", "isOnline", "category" ] } } } }, "responses": { "201": { "description": "Event created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Event" }, "message": { "type": "string" } }, "required": [ "ok", "success", "data", "message" ] } } } }, "400": { "description": "Validation error — missing required fields or invalid category" }, "401": { "description": "Unauthorized" } } } }, "/api/oriva/events/{eventId}": { "get": { "operationId": "getEvent", "tags": [ "Events" ], "summary": "Get event", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "eventId", "in": "path" } ], "responses": { "200": { "description": "Event details", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Event" } }, "required": [ "ok", "success", "data" ] } } } }, "404": { "description": "Event not found" } } } }, "/api/v1/me/tokens": { "post": { "operationId": "createPersonalAccessToken", "tags": [ "PersonalTokens" ], "summary": "Create a Personal Access Token", "description": "Issues a new Personal Access Token (PAT) scoped to the authenticated account. The full token value is returned **once** and cannot be retrieved again. PATs carry broad `[\"read\",\"write\"]` permissions and are intended for personal tooling (e.g. MCP servers).", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Human-readable label for the token" }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 expiry date. Omit for a non-expiring token." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Token created — contains the full one-time token value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedPersonalToken" } } } }, "400": { "description": "Validation error" }, "401": { "description": "Not authenticated" } } }, "get": { "operationId": "listPersonalAccessTokens", "tags": [ "PersonalTokens" ], "summary": "List Personal Access Tokens", "description": "Returns all PATs belonging to the authenticated account. Full token values and hashes are never returned.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of PATs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalTokenList" } } } }, "401": { "description": "Not authenticated" } } } }, "/api/v1/me/tokens/{id}": { "delete": { "operationId": "revokePersonalAccessToken", "tags": [ "PersonalTokens" ], "summary": "Revoke a Personal Access Token", "description": "Sets `is_active = false` on the token (soft-delete). The row is preserved for audit purposes. Returns 404 if the token does not belong to this account.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Revoked successfully" }, "401": { "description": "Not authenticated" }, "404": { "description": "Token not found or does not belong to this account" } } } }, "/api/v1/payments/payment-links": { "post": { "operationId": "createPaymentLink", "tags": [ "Payments" ], "summary": "Create a payment link (Checkout Session)", "description": "Creates a Stripe Checkout Session and returns a one-time hosted payment URL.\n\n**Funds-flow modes**\n\n| Mode | When | Who is charged | Oriva fee |\n|---|---|---|---|\n| **Direct Charge** | `merchant_connect_account_id` present | Buyer charged via merchant Connect account | 10% `application_fee_amount` deducted at charge time. `funds_flow=direct_charge` written to session metadata. |\n| **Separate Transfers** | `merchant_connect_account_id` absent | Buyer charged on Oriva platform account | REA cron distributes author share post-settlement. `funds_flow=separate_transfers` written to session metadata. |\n\nThe `funds_flow` field in the Stripe metadata is set automatically by the server based on the presence of `merchant_connect_account_id` — callers do not set it.\n\nRequires an active `oriva_pk_` API key whose owner has a registered REA agent record.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 1, "maximum": 99999999, "description": "Charge amount in the smallest currency unit (e.g. cents for USD). Range 1–99,999,999." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 three-letter currency code (e.g. \"usd\")." }, "description": { "type": "string", "maxLength": 500, "description": "Product description shown on the Stripe Checkout page." }, "merchant_connect_account_id": { "type": "string", "pattern": "^acct_[A-Za-z0-9]+$", "description": "Stripe Connect account ID (format: acct_…). When present the session runs as a Direct Charge: Stripe charges the buyer via the merchant account; Oriva collects a 10% application fee. When absent the session falls back to Separate Transfers: Oriva charges on the platform account and distributes via the REA payout cron." }, "oriva_manifest_id": { "type": "string", "format": "uuid", "description": "REA manifest UUID for skill royalty attribution." }, "oriva_invocation_id": { "type": "string", "format": "uuid", "description": "Unique invocation UUID for analytics and deduplication." }, "success_url": { "type": "string", "format": "uri", "description": "URL the buyer is redirected to after a successful payment. Must use https://." }, "cancel_url": { "type": "string", "format": "uri", "description": "URL the buyer is redirected to if they abandon the checkout. Must use https://." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value pairs forwarded to the Stripe Checkout Session metadata." } }, "required": [ "amount_cents", "currency", "success_url", "cancel_url" ] } } } }, "responses": { "200": { "description": "Checkout Session created. Redirect the buyer to `data.url`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "description": "Validation error — missing required field or invalid format" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Caller does not have a registered REA agent record. Register as a skill author at oriva.io/settings/developer before using this endpoint." }, "500": { "description": "Internal server error" }, "502": { "description": "Stripe API error — details in response body" } } } }, "/api/v1/bridge/connections": { "get": { "operationId": "listBridgeConnections", "tags": [ "Bridge" ], "summary": "List Bridge tool connections", "description": "Lists the external workflow tools connected for the authenticated account’s organizations, with connection status.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Connected tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeConnection" } } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } }, "post": { "operationId": "createBridgeConnection", "tags": [ "Bridge" ], "summary": "Connect a tool headlessly with an API token", "description": "Stores an API token for an external workflow tool so it can sync into the org’s bridges. Headless alternative to the in-app OAuth connect. Requires org admin.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBridgeConnectionBody" } } } }, "responses": { "200": { "description": "Connection stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/BridgeConnection" } }, "required": [ "ok", "success", "data" ] } } } }, "400": { "description": "Validation error" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Caller is not an admin of any organization" } } } }, "/api/v1/bridge/connections/{platform}": { "delete": { "operationId": "disconnectBridgeConnection", "tags": [ "Bridge" ], "summary": "Disconnect a tool", "description": "Removes the stored token for a platform across the caller’s organizations. Requires org admin.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "monday", "clickup", "asana", "notion" ], "example": "monday" }, "required": true, "name": "platform", "in": "path" } ], "responses": { "200": { "description": "Disconnected", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "monday", "clickup", "asana", "notion" ], "example": "monday" } }, "required": [ "platform" ] } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Caller is not an admin of any organization" } } } }, "/api/v1/bridge/groups": { "get": { "operationId": "listBridges", "tags": [ "Bridge" ], "summary": "List bridges", "description": "Lists the bridge groups the authenticated account’s organizations participate in.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Bridges", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeGroup" } } }, "required": [ "ok", "success", "data" ] } } } }, "401": { "description": "Invalid or missing API key" } } } }, "/api/v1/bridge/tasks": { "get": { "operationId": "listBridgeTasks", "tags": [ "Bridge" ], "summary": "List bridge tasks", "description": "Lists the canonical synced tasks in a bridge group. Pass ?bridgeGroupId=.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "bridgeGroupId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Bridge tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeTask" } } }, "required": [ "ok", "success", "data" ] } } } }, "400": { "description": "Validation error — missing or invalid bridgeGroupId" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Caller does not participate in this bridge" } } } }, "/api/v1/bridge/sync": { "post": { "operationId": "triggerBridgeSync", "tags": [ "Bridge" ], "summary": "Trigger a bridge sync", "description": "Enqueues a sync event for a bridge group so connected tools reconcile. Requires participation in the bridge.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerBridgeSyncBody" } } } }, "responses": { "202": { "description": "Sync enqueued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "bridgeGroupId": { "type": "string", "format": "uuid" }, "enqueued": { "type": "boolean" } }, "required": [ "bridgeGroupId", "enqueued" ] } }, "required": [ "ok", "success", "data" ] } } } }, "400": { "description": "Validation error" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Caller does not participate in this bridge" } } } }, "/api/agent/purchases": { "post": { "operationId": "buyListing", "tags": [ "Agent" ], "servers": [ { "url": "https://oriva.io", "description": "Oriva web app (o-core)" } ], "summary": "Buy a marketplace listing with the owner's money, within their limits", "description": "Spends the API key owner's REAL money: charges the card they saved, only after they switched agent buying on and only within the per-purchase and per-day limits they set at https://oriva.io/settings/agent-buying. Use only when the owner has asked you to buy this listing; do not use to check a price (read the listing first) or to browse.\n\n- `expectedAmountCents` must be the exact current total; a different price is refused.\n- Always send an `Idempotency-Key` and reuse it when retrying the same purchase; a repeat returns the first attempt (200, `repeat: true`) instead of buying twice.\n- 201 bought. 202 not finished yet: it still counts against the limits, so do NOT buy again; check `listAgentPurchases` later.\n- 403 `refused: true` is final (switched off, over a limit, price changed, own listing...): do not retry; tell the owner the reason.\n- 402 the card was not charged.\n\nAuthorised only by a personal access token (`Bearer oriva_pk_...`), never a browser session. Served by https://oriva.io, not api.oriva.io.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 200, "description": "Your id for this purchase attempt, up to 200 characters. Resending the same key returns the first attempt instead of buying again. Always send one, and reuse it when retrying the same purchase. If omitted, the SDK, CLI and MCP server generate one and report it." }, "required": false, "description": "Your id for this purchase attempt, up to 200 characters. Resending the same key returns the first attempt instead of buying again. Always send one, and reuse it when retrying the same purchase. If omitted, the SDK, CLI and MCP server generate one and report it.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyListingBody" } } } }, "responses": { "200": { "description": "Repeat of an earlier request with the same Idempotency-Key. Nothing new was bought.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseRepeat" } } } }, "201": { "description": "Bought. The card was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseBought" } } } }, "202": { "description": "Not finished yet. Still counts against the limits; check listAgentPurchases later. Do not buy again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchasePending" } } } }, "400": { "description": "Invalid input (listingId, expectedAmountCents, variantIndex or Idempotency-Key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "401": { "description": "Missing or invalid personal access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "402": { "description": "The card was not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseCardFailed" } } } }, "403": { "description": "Refused, and final: agent buying switched off, over a limit, price changed, own listing, or the account has no email. Do not retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseRefused" } } } } } }, "get": { "operationId": "listAgentPurchases", "tags": [ "Agent" ], "servers": [ { "url": "https://oriva.io", "description": "Oriva web app (o-core)" } ], "summary": "List the owner's recent agent purchases, refused ones included", "description": "Returns the API key owner's 50 most recent agent purchase attempts, newest first, with status and reason. Use to check on a purchase that answered 202, or to see what has been spent. Read-only; spends nothing. Served by https://oriva.io, not api.oriva.io.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Recent agent purchases.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseList" } } } }, "401": { "description": "Missing or invalid personal access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "403": { "description": "The account cannot be acted for by an agent (for example, it has no email).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } } } }, "/api/agent/listings": { "post": { "operationId": "createListing", "tags": [ "Agent" ], "servers": [ { "url": "https://oriva.io", "description": "Oriva web app (o-core)" } ], "summary": "List an item for sale in the marketplace in the owner's name", "description": "Creates a marketplace listing as the API key owner, under the same content check as one made in the browser. Works only once the owner has switched agent listing on at https://oriva.io/settings/agent-buying (off by default); at most 20 agent listings an hour. Use when the owner asks you to sell something. Do not use to buy (use `buyListing`) or to edit an existing listing.\n\n- 422: the content check refused it; `error` and `hint` say what to change before retrying.\n- 403: listing switched off, a paid listing needs a paid plan (retry with `publish: false` to save a draft), or the profile is not the owner's. Do not retry unchanged.\n- 429: over 20 listings an hour; wait before retrying.\n\nServed by https://oriva.io, not api.oriva.io.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateListingBody" } } } }, "responses": { "201": { "description": "Listed (or saved as a draft when publish was false).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListingCreated" } } } }, "400": { "description": "Invalid input — the message names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "401": { "description": "Missing or invalid personal access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "403": { "description": "Agent listing switched off, paid listing on a free plan, no named profile, or a profile that is not the owner's.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "422": { "description": "Refused by the content check. Change what `hint` says and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListingContentRefused" } } } }, "429": { "description": "More than 20 agent listings in the last hour. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } } } } }, "webhooks": {} }