{ "openapi": "3.0.3", "info": { "title": "Mind Upload Partner API", "version": "1.5.9", "description": "Integrate Mind Upload AI consciousnesses into your own platform.\n\n**Authentication.** Every request carries your partner key in the `X-Partner-Key` header, always over TLS. Your end-users sign in once with their `username` and `password`; `login` and `register` return a signed, expiring session token (a JWT). On every subsequent call, send that token in the `password` field in place of the raw password — the field accepts either. Reusing the token is the recommended flow and a deliberate security choice: your platform never has to store or replay a user's actual password, and tokens can be rotated or simply left to expire. External Authorization provides passwordless, owner-approved clone invocation without exposing a native password or session token. Grant tokens are accepted only by grant inspection and external clone invocation; never substitute them for native session tokens.\n\n**Calling convention.** Every operation is a single HTTPS POST of a JSON body to `/v1/{operation}`.\n\n**Rate limits.** Limits apply per end-user (with optional overall account ceilings); a 429 response carries a plain-language message. Contact us to raise your limits.\n\n**Getting a key.** Partner keys are issued on request — tell us about your integration and we will review it and reply." }, "servers": [ { "url": "https://partner.mindupload.app" } ], "tags": [ { "name": "Authentication", "description": "Sign users in and out, register accounts, and check username availability." }, { "name": "Users", "description": "Read and update the signed-in user's profile." }, { "name": "AI Consciousnesses", "description": "Create and manage a user's AI consciousnesses (clones)." }, { "name": "Memories", "description": "Upload and list the memories and persona that shape an AI consciousness." }, { "name": "Conversation", "description": "One-on-one chat and proactive group replies with an AI consciousness." }, { "name": "Insights", "description": "Mind-graph visualization and two-member compatibility reports." }, { "name": "Chatrooms", "description": "Create chatrooms, manage members, and exchange messages." }, { "name": "Media", "description": "Signed upload slots and multipart uploads for media attachments." }, { "name": "External Authorization", "description": "Owner-approved grant issuance, inspection, and clone-scoped invocation." }, { "name": "Account", "description": "Your partner account — rate limits, credit caps, capacity, and current usage." } ], "components": { "securitySchemes": { "PartnerKey": { "type": "apiKey", "in": "header", "name": "X-Partner-Key" } } }, "paths": { "/v1/login": { "post": { "operationId": "login", "summary": "Sign a user in and receive a session token (JWT) for subsequent calls.", "tags": [ "Authentication" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "jwt": { "type": "string", "nullable": true }, "decrypted_user": { "type": "object", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/logout": { "post": { "operationId": "logout", "summary": "End the current user session.", "tags": [ "Authentication" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "revoked": { "type": "boolean", "nullable": true }, "operation_duration_ms": { "type": "number", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/register": { "post": { "operationId": "register", "summary": "Create a user account on your platform.", "tags": [ "Authentication" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "email": { "type": "string", "nullable": true }, "email_verification_code": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "birth_date": { "type": "integer", "nullable": true }, "phone_number": { "type": "string", "nullable": true }, "avatar_id": { "type": "string", "nullable": true }, "accept_chatroom_invitation_by_others": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "jwt": { "type": "string", "nullable": true }, "decrypted_user": { "type": "object", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/check_username": { "post": { "operationId": "check_username", "summary": "Check whether a username is still available before registering.", "tags": [ "Authentication" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "exists": { "type": "boolean", "nullable": true }, "disabled": { "type": "boolean", "nullable": true }, "rate_limited": { "type": "boolean", "nullable": true }, "flood_window": { "type": "string", "nullable": true }, "wait_seconds": { "type": "integer", "nullable": true }, "operation_duration_ms": { "type": "number", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_user": { "post": { "operationId": "get_user", "summary": "Fetch the signed-in user's profile.", "tags": [ "Users" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "jwt": { "type": "string", "nullable": true }, "decrypted_user": { "type": "object", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/update_user": { "post": { "operationId": "update_user", "summary": "Update the signed-in user's profile.", "tags": [ "Users" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "email": { "type": "string", "nullable": true }, "email_verification_code": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "birth_date": { "type": "integer", "nullable": true }, "phone_number": { "type": "string", "nullable": true }, "avatar_id": { "type": "string", "nullable": true }, "accept_chatroom_invitation_by_others": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_quota": { "post": { "operationId": "get_quota", "summary": "Check your partner API rate limits, credit caps, and current usage.", "tags": [ "Account" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "per_user_rate_limit_per_min": { "type": "integer", "nullable": true, "description": "Requests allowed per minute for each of your end-users." }, "per_user_daily_credit_cap": { "type": "integer", "nullable": true, "description": "Credit-spending calls allowed per rolling 24h for each end-user." }, "partner_rate_limit_per_min": { "type": "integer", "nullable": true, "description": "Optional account-wide requests/min ceiling across all your users; null means no aggregate limit." }, "external_authorization_rate_limit_per_min": { "type": "integer", "nullable": true, "description": "Effective account-wide requests/min ceiling for external authorization operations." }, "partner_daily_credit_cap": { "type": "integer", "nullable": true, "description": "Optional account-wide credit-spending calls per rolling 24h; null means no aggregate limit." }, "max_users": { "type": "integer", "nullable": true, "description": "Maximum end-users you may register; null means unlimited." }, "registered_users": { "type": "integer", "nullable": true, "description": "How many end-users you have registered so far." }, "partner_requests_last_minute": { "type": "integer", "nullable": true, "description": "Your requests across all users in the last 60 seconds." }, "partner_credit_spends_last_day": { "type": "integer", "nullable": true, "description": "Your credit-spending calls across all users in the last 24 hours." }, "user": { "type": "string", "nullable": true, "description": "The end-user the per-user figures below are scoped to (echoes your request)." }, "user_requests_last_minute": { "type": "integer", "nullable": true, "description": "This user's requests in the last 60 seconds (present only when you pass a username)." }, "user_credit_spends_last_day": { "type": "integer", "nullable": true, "description": "This user's credit-spending calls in the last 24 hours (present only when you pass a username)." }, "credit_spending_tasks": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Which operations count toward the credit-spend caps." }, "operation_duration_ms": { "type": "number", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/create_external_authorization_request": { "post": { "operationId": "create_external_authorization_request", "summary": "Start passwordless grant issuance for an external identity and installation.", "description": "Use this when a person on your platform already has a Mind Upload account. Store the returned device code only for the short authorization window. Show the user code and verification link to the person; they review the application, requested scopes, and selected AI consciousnesses on Mind Upload.", "tags": [ "External Authorization" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "idempotency_key": { "type": "string", "description": "A stable opaque event key that makes exact retries return the same outcome.", "example": "unique-request-id-from-your-system", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "installation_id": { "type": "string", "description": "Your stable opaque identifier for this app installation.", "example": "your-installation-id", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "external_subject": { "type": "string", "description": "Your stable opaque identifier for the person authorizing this installation.", "example": "your-external-user-id", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "installation_label": { "type": "string", "nullable": true, "description": "Optional user-readable name for the installation shown during consent.", "example": "Work laptop", "minLength": 1, "maxLength": 120, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "external_identity_label": { "type": "string", "nullable": true, "description": "Optional user-readable external identity shown during consent.", "example": "External account", "minLength": 1, "maxLength": 120, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "requested_scopes": { "type": "array", "items": { "type": "string", "enum": [ "clone:invoke" ] }, "description": "Capabilities the owner is being asked to delegate.", "example": [ "clone:invoke" ], "minItems": 1, "uniqueItems": true, "maxItems": 10 } }, "required": [ "external_subject", "idempotency_key", "installation_id", "requested_scopes" ] } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "device_code": { "type": "string", "nullable": true, "description": "Short-lived high-entropy secret used only to poll and exchange this request." }, "user_code": { "type": "string", "nullable": true, "description": "Short-lived human-entered code shown to the owner." }, "verification_uri": { "type": "string", "nullable": true, "description": "Mind Upload location where the owner reviews the request." }, "verification_uri_complete": { "type": "string", "nullable": true, "description": "Verification location with the human code prefilled." }, "expires_in": { "type": "integer", "nullable": true, "description": "Seconds until the device authorization request expires." }, "poll_interval": { "type": "integer", "nullable": true, "description": "Minimum seconds to wait between exchange polls." }, "grant_duration_seconds": { "type": "integer", "nullable": true, "description": "Grant lifetime shown to the owner before consent." } }, "required": [ "device_code", "error_message", "expires_in", "grant_duration_seconds", "poll_interval", "success", "user_code", "verification_uri", "verification_uri_complete" ] } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/exchange_external_authorization": { "post": { "operationId": "exchange_external_authorization", "summary": "Poll owner consent and exchange an approval for a clone-scoped grant token.", "description": "Poll no faster than `poll_interval`. `pending`, `slow_down`, and `denied` are successful protocol states without a token. After approval, repeated calls with the same unexpired device code return the same grant token, which makes a lost response safe to retry.", "tags": [ "External Authorization" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "device_code": { "type": "string", "description": "Short-lived high-entropy secret used only to poll and exchange this request.", "example": "device-code-from-create-response", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" } }, "required": [ "device_code" ] } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "status": { "type": "string", "nullable": true, "description": "Current authorization or invocation lifecycle state.", "enum": [ "pending", "slow_down", "denied", "expired", "revoked", "exchanged" ] }, "access_token": { "type": "string", "nullable": true, "description": "Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users." }, "refresh_token": { "type": "string", "nullable": true, "description": "Opaque grant-lifetime token used only with refresh_external_authorization; store it as a secret." }, "token_type": { "type": "string", "nullable": true, "description": "Authorization token type.", "enum": [ "Bearer" ] }, "grant_id": { "type": "string", "nullable": true, "description": "Stable grant identifier used by the owner-facing revocation surface." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "clone:invoke" ] }, "nullable": true, "description": "Capabilities approved by the owner.", "minItems": 1, "uniqueItems": true }, "clone_ids": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "AI consciousness resources selected by the owner." }, "access_token_expires_at": { "type": "integer", "nullable": true, "description": "UNIX timestamp after which the short-lived access token must be refreshed." }, "expires_at": { "type": "integer", "nullable": true, "description": "UNIX timestamp after which this request or grant is no longer valid." }, "poll_interval": { "type": "integer", "nullable": true, "description": "Minimum seconds to wait between exchange polls." } }, "required": [ "access_token", "access_token_expires_at", "clone_ids", "error_message", "expires_at", "grant_id", "poll_interval", "refresh_token", "scopes", "status", "success", "token_type" ] } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/refresh_external_authorization": { "post": { "operationId": "refresh_external_authorization", "summary": "Refresh a short-lived clone-invocation access token.", "description": "Use the grant-lifetime refresh token before the access token expires. The refresh token is bound to the same authenticated application, installation, and external identity. Concurrent or repeated refreshes return the same current access token and never extend the owner-approved grant expiry.", "tags": [ "External Authorization" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "refresh_token": { "type": "string", "description": "Opaque grant-lifetime token used only with refresh_external_authorization; store it as a secret.", "example": "refresh-token-from-exchange-response", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "installation_id": { "type": "string", "description": "Your stable opaque identifier for this app installation.", "example": "your-installation-id", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "external_subject": { "type": "string", "description": "Your stable opaque identifier for the person authorizing this installation.", "example": "your-external-user-id", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" } }, "required": [ "external_subject", "installation_id", "refresh_token" ] } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "status": { "type": "string", "nullable": true, "description": "Current authorization or invocation lifecycle state.", "enum": [ "active", "revoked", "expired" ] }, "access_token": { "type": "string", "nullable": true, "description": "Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users." }, "refresh_token": { "type": "string", "nullable": true, "description": "Opaque grant-lifetime token used only with refresh_external_authorization; store it as a secret." }, "token_type": { "type": "string", "nullable": true, "description": "Authorization token type.", "enum": [ "Bearer" ] }, "grant_id": { "type": "string", "nullable": true, "description": "Stable grant identifier used by the owner-facing revocation surface." }, "scopes": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Capabilities approved by the owner." }, "clone_ids": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "AI consciousness resources selected by the owner." }, "access_token_expires_at": { "type": "integer", "nullable": true, "description": "UNIX timestamp after which the short-lived access token must be refreshed." }, "expires_at": { "type": "integer", "nullable": true, "description": "UNIX timestamp after which this request or grant is no longer valid." } }, "required": [ "access_token", "access_token_expires_at", "clone_ids", "error_message", "expires_at", "grant_id", "refresh_token", "scopes", "status", "success", "token_type" ] } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/inspect_external_authorization": { "post": { "operationId": "inspect_external_authorization", "summary": "Inspect the scopes, clone resources, expiry, and revocation state of a grant token.", "description": "Returns only authorization metadata. It never returns an owner password, session token, external identifier, memory, or conversation content.", "tags": [ "External Authorization" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "access_token": { "type": "string", "description": "Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users.", "example": "grant-token-from-exchange-response", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" } }, "required": [ "access_token" ] } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "grant_id": { "type": "string", "nullable": true, "description": "Stable grant identifier used by the owner-facing revocation surface." }, "status": { "type": "string", "nullable": true, "description": "Current authorization or invocation lifecycle state.", "enum": [ "active", "revoked", "expired" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "clone:invoke" ] }, "nullable": true, "description": "Capabilities approved by the owner.", "minItems": 1, "uniqueItems": true }, "clone_ids": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "AI consciousness resources selected by the owner." }, "created_at": { "type": "integer", "nullable": true }, "access_token_expires_at": { "type": "integer", "nullable": true, "description": "UNIX timestamp after which the short-lived access token must be refreshed." }, "expires_at": { "type": "integer", "nullable": true, "description": "UNIX timestamp after which this request or grant is no longer valid." }, "revoked_at": { "type": "integer", "nullable": true, "description": "UNIX timestamp when the owner revoked the grant, or null." } }, "required": [ "access_token_expires_at", "clone_ids", "created_at", "error_message", "expires_at", "grant_id", "revoked_at", "scopes", "status", "success" ] } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/invoke_external_clone": { "post": { "operationId": "invoke_external_clone", "summary": "Send one idempotent text event to an owner-approved AI consciousness.", "description": "Requires the partner key plus an active `clone:invoke` grant bound to the same installation, external identity, and clone. Use a provider event id as `idempotency_key`: exact retries return the stored encrypted outcome and never run generation twice. A concurrent retry returns `processing` with `retry_after_seconds`; an abandoned receipt eventually becomes terminal `failed` and is not regenerated with the same key. This initial transport is text-only. The owner must retain normal subscription entitlement; this operation does not spend credits.", "tags": [ "External Authorization" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "access_token": { "type": "string", "description": "Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users.", "example": "grant-token-from-exchange-response", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "installation_id": { "type": "string", "description": "Your stable opaque identifier for this app installation.", "example": "your-installation-id", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "external_subject": { "type": "string", "description": "Your stable opaque identifier for the person authorizing this installation.", "example": "your-external-user-id", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" }, "clone_id": { "type": "string", "example": "64f0c8b2f7a9b4e1c2d3a456", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-fA-F]{24}$" }, "text": { "type": "string", "example": "Hello from your external app.", "minLength": 1, "maxLength": 8000, "pattern": "^[^\\x00]*\\S[^\\x00]*$" }, "idempotency_key": { "type": "string", "description": "A stable opaque event key that makes exact retries return the same outcome.", "example": "provider-event-id", "minLength": 1, "maxLength": 256, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" } }, "required": [ "access_token", "clone_id", "external_subject", "idempotency_key", "installation_id", "text" ] } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "invocation_id": { "type": "string", "nullable": true, "description": "Stable receipt identifier for this external event." }, "status": { "type": "string", "nullable": true, "description": "Current authorization or invocation lifecycle state.", "enum": [ "processing", "succeeded", "failed" ] }, "response_text": { "type": "string", "nullable": true, "description": "The AI consciousness reply when status is `succeeded`." }, "clone_id": { "type": "string", "nullable": true }, "clone_nickname": { "type": "string", "nullable": true, "description": "User-facing name of the invoked AI consciousness." }, "generated_by_ai": { "type": "boolean", "nullable": true, "description": "True when the returned response was generated by an AI consciousness." }, "idempotent_replay": { "type": "boolean", "nullable": true, "description": "True when this response came from an existing durable receipt." }, "retry_after_seconds": { "type": "integer", "nullable": true, "description": "Suggested delay before retrying the same event while processing." } }, "required": [ "clone_id", "clone_nickname", "error_message", "generated_by_ai", "idempotent_replay", "invocation_id", "response_text", "retry_after_seconds", "status", "success" ] } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_clones": { "post": { "operationId": "get_clones", "summary": "List the user's AI consciousnesses.", "tags": [ "AI Consciousnesses" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "clones": { "type": "array", "items": { "type": "object" }, "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/create_clone": { "post": { "operationId": "create_clone", "summary": "Create a new AI consciousness for the user.", "tags": [ "AI Consciousnesses" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "codename": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "avatar_id": { "type": "string", "nullable": true }, "accept_chatroom_invitation_by_others": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/update_clone": { "post": { "operationId": "update_clone", "summary": "Update an AI consciousness's profile.", "tags": [ "AI Consciousnesses" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "codename": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "avatar_id": { "type": "string", "nullable": true }, "accept_chatroom_invitation_by_others": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_texts": { "post": { "operationId": "get_texts", "summary": "List the memories and persona entries uploaded to an AI consciousness.", "tags": [ "Memories" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "page": { "type": "integer", "nullable": true, "default": 1 }, "page_size": { "type": "integer", "default": 30 }, "sort_by": { "type": "string", "nullable": true, "default": "created_at" }, "sort_order": { "type": "integer", "nullable": true, "default": -1 }, "use_cursor_pagination": { "type": "boolean", "nullable": true, "default": true }, "cursor_value": { "type": "string", "nullable": true }, "cursor_id": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "codename": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "total_count": { "type": "integer", "nullable": true }, "page": { "type": "integer", "nullable": true }, "page_size": { "type": "integer", "nullable": true }, "total_pages": { "type": "integer", "nullable": true }, "has_next": { "type": "boolean", "nullable": true }, "has_prev": { "type": "boolean", "nullable": true }, "next_cursor_value": { "type": "string", "nullable": true }, "next_cursor_id": { "type": "string", "nullable": true }, "texts": { "type": "array", "items": { "type": "object" }, "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/create_text": { "post": { "operationId": "create_text", "summary": "Upload a memory or persona entry to an AI consciousness.", "tags": [ "Memories" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "codename": { "type": "string", "nullable": true }, "clone_id": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "cluster_label": { "type": "string", "nullable": true }, "cluster_modified_count": { "type": "integer", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_chat": { "post": { "operationId": "get_chat", "summary": "Fetch the one-on-one conversation history with an AI consciousness.", "tags": [ "Conversation" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "page": { "type": "integer", "nullable": true, "default": 1 }, "page_size": { "type": "integer", "default": 30 }, "sort_by": { "type": "string", "nullable": true, "default": "created_at" }, "sort_order": { "type": "integer", "nullable": true, "default": -1 }, "use_cursor_pagination": { "type": "boolean", "nullable": true, "default": true }, "cursor_value": { "type": "string", "nullable": true }, "cursor_id": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "codename": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "total_count": { "type": "integer", "nullable": true }, "page": { "type": "integer", "nullable": true }, "page_size": { "type": "integer", "nullable": true }, "total_pages": { "type": "integer", "nullable": true }, "has_next": { "type": "boolean", "nullable": true }, "has_prev": { "type": "boolean", "nullable": true }, "next_cursor_value": { "type": "string", "nullable": true }, "next_cursor_id": { "type": "string", "nullable": true }, "chats": { "type": "array", "items": { "type": "object" }, "nullable": true }, "media_thumbnails": { "type": "object", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/rag": { "post": { "operationId": "rag", "summary": "Send a message to an AI consciousness and receive its reply.", "tags": [ "Conversation" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "codename": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "response_text": { "type": "string", "nullable": true, "description": "The AI consciousness reply when status is `succeeded`." }, "clone_nickname": { "type": "string", "nullable": true, "description": "User-facing name of the invoked AI consciousness." }, "consolidation_summary": { "type": "string", "nullable": true }, "consolidation_count": { "type": "integer", "nullable": true }, "consolidation_dispatched": { "type": "boolean", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/trigger_social": { "post": { "operationId": "trigger_social", "summary": "Have an AI consciousness proactively join the conversation in a chatroom.", "tags": [ "Conversation" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "membership_id": { "type": "string", "nullable": true }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "response_text": { "type": "string", "nullable": true, "description": "The AI consciousness reply when status is `succeeded`." }, "chatroom_digests_count": { "type": "integer", "nullable": true }, "chatroom_digests_summary": { "type": "string", "nullable": true }, "consolidation_summary": { "type": "string", "nullable": true }, "consolidation_count": { "type": "integer", "nullable": true }, "consolidation_dispatched": { "type": "boolean", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_mind_cluster": { "post": { "operationId": "get_mind_cluster", "summary": "Fetch the mind-graph visualization data of an AI consciousness.", "tags": [ "Insights" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "codename": { "type": "string", "nullable": true }, "node_id": { "type": "string", "nullable": true }, "texts_offset": { "type": "integer", "nullable": true, "default": 0 }, "texts_page_size": { "type": "integer", "nullable": true }, "force_rebuild": { "type": "boolean", "nullable": true, "default": false } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "root_node_id": { "type": "string", "nullable": true }, "node": { "type": "object", "nullable": true }, "children": { "type": "array", "items": { "type": "object" }, "nullable": true }, "texts": { "type": "array", "items": { "type": "object" }, "nullable": true }, "total_texts": { "type": "integer", "nullable": true }, "texts_offset": { "type": "integer", "nullable": true }, "has_more_texts": { "type": "boolean", "nullable": true }, "is_building": { "type": "boolean", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_soulmate_report": { "post": { "operationId": "get_soulmate_report", "summary": "Generate or fetch the compatibility report between two chatroom members.", "tags": [ "Insights" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "my_clone_id": { "type": "string", "nullable": true }, "other_clone_id": { "type": "string", "nullable": true }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "report": { "type": "object", "nullable": true }, "report_generated_at": { "type": "integer", "nullable": true }, "is_generating": { "type": "boolean", "nullable": true }, "charged": { "type": "boolean", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/create_chatroom": { "post": { "operationId": "create_chatroom", "summary": "Create a chatroom.", "tags": [ "Chatrooms" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "chatroom_name": { "type": "string", "nullable": true }, "is_public": { "type": "boolean", "nullable": true }, "avatar_id": { "type": "string", "nullable": true }, "soulmate_check_enabled": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_chatrooms": { "post": { "operationId": "get_chatrooms", "summary": "List the chatrooms the user belongs to.", "tags": [ "Chatrooms" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "page": { "type": "integer", "nullable": true, "default": 1 }, "page_size": { "type": "integer", "default": 10000 }, "sort_by": { "type": "string", "nullable": true, "default": "created_at" }, "sort_order": { "type": "integer", "nullable": true, "default": -1 }, "use_cursor_pagination": { "type": "boolean", "nullable": true, "default": true }, "cursor_value": { "type": "string", "nullable": true }, "cursor_id": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "get_public": { "type": "boolean", "nullable": true }, "get_private": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "total_count": { "type": "integer", "nullable": true }, "page": { "type": "integer", "nullable": true }, "page_size": { "type": "integer", "nullable": true }, "total_pages": { "type": "integer", "nullable": true }, "has_next": { "type": "boolean", "nullable": true }, "has_prev": { "type": "boolean", "nullable": true }, "next_cursor_value": { "type": "string", "nullable": true }, "next_cursor_id": { "type": "string", "nullable": true }, "chatrooms": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "Chatroom-related objects for this operation." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/create_chatroom_message": { "post": { "operationId": "create_chatroom_message", "summary": "Send a message to a chatroom.", "tags": [ "Chatrooms" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." }, "text": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "message_id": { "type": "string", "nullable": true, "description": "Chatroom message id." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_chatroom_messages": { "post": { "operationId": "get_chatroom_messages", "summary": "Fetch messages from a chatroom the user belongs to.", "tags": [ "Chatrooms" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "page": { "type": "integer", "nullable": true, "default": 1 }, "page_size": { "type": "integer", "default": 30 }, "sort_by": { "type": "string", "nullable": true, "default": "created_at" }, "sort_order": { "type": "integer", "nullable": true, "default": -1 }, "use_cursor_pagination": { "type": "boolean", "nullable": true, "default": true }, "cursor_value": { "type": "string", "nullable": true }, "cursor_id": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." }, "since_value": { "type": "number", "nullable": true }, "since_id": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "total_count": { "type": "integer", "nullable": true }, "page": { "type": "integer", "nullable": true }, "page_size": { "type": "integer", "nullable": true }, "total_pages": { "type": "integer", "nullable": true }, "has_next": { "type": "boolean", "nullable": true }, "has_prev": { "type": "boolean", "nullable": true }, "next_cursor_value": { "type": "string", "nullable": true }, "next_cursor_id": { "type": "string", "nullable": true }, "messages": { "type": "array", "items": { "type": "object" }, "nullable": true }, "media_thumbnails": { "type": "object", "nullable": true }, "since_overflow": { "type": "boolean", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/translate_chatroom_message": { "post": { "operationId": "translate_chatroom_message", "summary": "Translate a text chatroom message into the viewer language.", "description": "Translates one text chatroom message into `preferred_language`. This operation requires an active subscription for the end-user. The message body is translated by Mind Upload, and repeated requests may return a cached translation until the source message changes. Reply quotes and media tags are ignored so only the human-readable text body is translated. Very large text messages may be rejected with a validation error before work starts.", "tags": [ "Chatrooms" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." }, "message_id": { "type": "string", "nullable": true, "description": "Chatroom message id." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "translated_text": { "type": "string", "nullable": true }, "target_language": { "type": "string", "nullable": true }, "cached": { "type": "boolean", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/check_chatroom_updates": { "post": { "operationId": "check_chatroom_updates", "summary": "Cheaply poll whether the user's chatrooms have new activity.", "description": "Cheap poll endpoint for chatroom freshness. Send each local chatroom id with the last `updated_at` value you saw, or `null` on the first poll. The response echoes one result per requested room in request order, tells you whether the room is still accessible, and returns `has_updates` when you should fetch new messages.", "tags": [ "Chatrooms" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "chatrooms": { "type": "array", "items": { "type": "object", "properties": { "chatroom_id": { "type": "string", "description": "Chatroom id as returned by chatroom operations." }, "known_updated_at": { "type": "number", "nullable": true, "description": "The last `updated_at` value your client has for this room, or null on the first poll." } }, "required": [ "chatroom_id" ] }, "nullable": true, "description": "Rooms to check. Each entry must include `chatroom_id`; include `known_updated_at` from the previous response, or null/omit it on the first poll.", "example": [ { "chatroom_id": "64f0c8b2f7a9b4e1c2d3a456", "known_updated_at": 1720000000.123 }, { "chatroom_id": "64f0c8b2f7a9b4e1c2d3a457", "known_updated_at": null } ] } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "server_time": { "type": "number", "nullable": true, "description": "Current server timestamp, useful for client-side poll scheduling." }, "poll_config": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether adaptive chatroom polling is enabled." }, "hot_seconds": { "type": "integer", "description": "Suggested short polling interval while the room is active." }, "max_seconds": { "type": "integer", "description": "Suggested longest polling interval while the room is idle." }, "hot_window_seconds": { "type": "integer", "description": "How long recent activity keeps a room in the hot polling window." } }, "required": [ "enabled", "hot_seconds", "hot_window_seconds", "max_seconds" ], "nullable": true, "description": "Recommended polling cadence for adaptive chatroom polling." }, "chatrooms": { "type": "array", "items": { "type": "object", "properties": { "chatroom_id": { "type": "string", "description": "Chatroom id as returned by chatroom operations." }, "accessible": { "type": "boolean", "description": "Whether the caller can currently read this room." }, "updated_at": { "type": "number", "nullable": true, "description": "Opaque freshness watermark to send back as `known_updated_at` on the next poll." }, "has_updates": { "type": "boolean", "description": "True when the room changed after the supplied `known_updated_at` value." } }, "required": [ "accessible", "chatroom_id", "has_updates", "updated_at" ] }, "nullable": true, "description": "One freshness result per requested room, in the same order as the request." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/create_chatroom_membership": { "post": { "operationId": "create_chatroom_membership", "summary": "Invite a user or an AI consciousness into a chatroom.", "tags": [ "Chatrooms" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." }, "invitee_username": { "type": "string", "nullable": true }, "invitee_codename": { "type": "string", "nullable": true }, "admin_level": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "membership_id": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/get_chatroom_membership": { "post": { "operationId": "get_chatroom_membership", "summary": "List the members of a chatroom the user belongs to.", "tags": [ "Chatrooms" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "page": { "type": "integer", "nullable": true, "default": 1 }, "page_size": { "type": "integer", "default": 10000 }, "sort_by": { "type": "string", "nullable": true, "default": "created_at" }, "sort_order": { "type": "integer", "nullable": true, "default": -1 }, "use_cursor_pagination": { "type": "boolean", "nullable": true, "default": true }, "cursor_value": { "type": "string", "nullable": true }, "cursor_id": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "chatroom_id": { "type": "string", "nullable": true, "description": "Chatroom id as returned by chatroom operations." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "total_count": { "type": "integer", "nullable": true }, "page": { "type": "integer", "nullable": true }, "page_size": { "type": "integer", "nullable": true }, "total_pages": { "type": "integer", "nullable": true }, "has_next": { "type": "boolean", "nullable": true }, "has_prev": { "type": "boolean", "nullable": true }, "next_cursor_value": { "type": "string", "nullable": true }, "next_cursor_id": { "type": "string", "nullable": true }, "memberships": { "type": "array", "items": { "type": "object" }, "nullable": true } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/request_upload_url": { "post": { "operationId": "request_upload_url", "summary": "Request an upload slot and a signed viewing link for a media attachment.", "tags": [ "Media" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "filename": { "type": "string", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "file_size_bytes": { "type": "integer", "nullable": true }, "media_type": { "type": "string", "nullable": true }, "has_thumbnail": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "r2_key": { "type": "string", "nullable": true, "description": "Opaque media object key returned by upload-start operations and reused for multipart upload calls." }, "presigned_url": { "type": "string", "nullable": true, "description": "Temporary URL where the client uploads the file or part." }, "media_url": { "type": "string", "nullable": true, "description": "Stable media URL to embed in a chat message after upload completes." }, "signed_media_url": { "type": "string", "nullable": true, "description": "Temporary readable media URL." }, "thumbnail_r2_key": { "type": "string", "nullable": true, "description": "Opaque thumbnail media object key, present only when a thumbnail upload was requested." }, "thumbnail_presigned_url": { "type": "string", "nullable": true, "description": "Temporary URL where the client uploads the thumbnail." }, "signed_thumbnail_url": { "type": "string", "nullable": true, "description": "Temporary readable thumbnail URL." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/request_multipart_upload": { "post": { "operationId": "request_multipart_upload", "summary": "Start a large-file upload in multiple parts.", "tags": [ "Media" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "filename": { "type": "string", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "file_size_bytes": { "type": "integer", "nullable": true }, "media_type": { "type": "string", "nullable": true }, "has_thumbnail": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "upload_id": { "type": "string", "nullable": true, "description": "Multipart upload session id returned by `request_multipart_upload`." }, "r2_key": { "type": "string", "nullable": true, "description": "Opaque media object key returned by upload-start operations and reused for multipart upload calls." }, "media_url": { "type": "string", "nullable": true, "description": "Stable media URL to embed in a chat message after upload completes." }, "signed_media_url": { "type": "string", "nullable": true, "description": "Temporary readable media URL." }, "thumbnail_r2_key": { "type": "string", "nullable": true, "description": "Opaque thumbnail media object key, present only when a thumbnail upload was requested." }, "thumbnail_presigned_url": { "type": "string", "nullable": true, "description": "Temporary URL where the client uploads the thumbnail." }, "signed_thumbnail_url": { "type": "string", "nullable": true, "description": "Temporary readable thumbnail URL." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/sign_upload_part": { "post": { "operationId": "sign_upload_part", "summary": "Get the signed link for one part of a multipart upload.", "tags": [ "Media" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "r2_key": { "type": "string", "nullable": true, "description": "Opaque media object key returned by upload-start operations and reused for multipart upload calls." }, "upload_id": { "type": "string", "nullable": true, "description": "Multipart upload session id returned by `request_multipart_upload`." }, "part_number": { "type": "integer", "nullable": true, "description": "One-based multipart part number." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "presigned_url": { "type": "string", "nullable": true, "description": "Temporary URL where the client uploads the file or part." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/sign_upload_parts_batch": { "post": { "operationId": "sign_upload_parts_batch", "summary": "Get signed links for several parts of a multipart upload at once.", "tags": [ "Media" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "r2_key": { "type": "string", "nullable": true, "description": "Opaque media object key returned by upload-start operations and reused for multipart upload calls." }, "upload_id": { "type": "string", "nullable": true, "description": "Multipart upload session id returned by `request_multipart_upload`." }, "part_numbers": { "type": "array", "items": { "type": "integer" }, "nullable": true, "description": "One-based multipart part numbers to sign in a single batch." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "presigned_urls": { "type": "object", "nullable": true, "description": "Temporary upload URLs keyed by multipart part number." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/list_upload_parts": { "post": { "operationId": "list_upload_parts", "summary": "List the parts already uploaded in a multipart upload.", "tags": [ "Media" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "r2_key": { "type": "string", "nullable": true, "description": "Opaque media object key returned by upload-start operations and reused for multipart upload calls." }, "upload_id": { "type": "string", "nullable": true, "description": "Multipart upload session id returned by `request_multipart_upload`." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "parts": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "Completed multipart upload parts in ascending part-number order." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/complete_multipart_upload": { "post": { "operationId": "complete_multipart_upload", "summary": "Finish a multipart upload.", "tags": [ "Media" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "r2_key": { "type": "string", "nullable": true, "description": "Opaque media object key returned by upload-start operations and reused for multipart upload calls." }, "upload_id": { "type": "string", "nullable": true, "description": "Multipart upload session id returned by `request_multipart_upload`." }, "parts": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "The successfully uploaded parts, using the `part_number` and `etag` returned by each part upload.", "example": [ { "part_number": 1, "etag": "\"9b2cf535f27731c974343645a3985328\"" }, { "part_number": 2, "etag": "\"4c6426ac7ef186464ecbb0d81cbfcb1e\"" } ] } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." }, "media_url": { "type": "string", "nullable": true, "description": "Stable media URL to embed in a chat message after upload completes." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/abort_multipart_upload": { "post": { "operationId": "abort_multipart_upload", "summary": "Cancel a multipart upload and discard its parts.", "tags": [ "Media" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "r2_key": { "type": "string", "nullable": true, "description": "Opaque media object key returned by upload-start operations and reused for multipart upload calls." }, "upload_id": { "type": "string", "nullable": true, "description": "Multipart upload session id returned by `request_multipart_upload`." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } }, "/v1/cancel_upload": { "post": { "operationId": "cancel_upload", "summary": "Cancel a pending upload.", "tags": [ "Media" ], "security": [ { "PartnerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferred_language": { "type": "string", "nullable": true, "description": "BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages." }, "username": { "type": "string", "nullable": true, "description": "The end-user's username." }, "password": { "type": "string", "nullable": true, "description": "The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage." }, "r2_key": { "type": "string", "nullable": true, "description": "Opaque media object key returned by upload-start operations and reused for multipart upload calls." } } } } } }, "responses": { "200": { "description": "Result envelope — check the success field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the call succeeded." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason when success is false." } } } } } }, "400": { "description": "Invalid request payload." }, "401": { "description": "Missing or invalid partner key." }, "403": { "description": "Partner is not authorized for this operation." }, "429": { "description": "Rate limit exceeded — retry later." }, "500": { "description": "Internal server error." } } } } } }