{"components":{"schemas":{"APIError":{"properties":{"code":{"example":"INVALID_REQUEST","type":"string"},"details":{"nullable":true,"type":"object"},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message"],"type":"object"},"Agent":{"properties":{"archived_at":{"description":"set once the agent is archived: swept to zero, its keys revoked","format":"date-time","nullable":true,"type":"string"},"balance_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"colour":{"enum":["cobalt","orchid","sky","mint","lemon","rose","lime"],"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"description":"what the agent is for, in its owner's words","type":"string"},"face":{"enum":["circle","squircle","hexagon","flower"],"type":"string"},"handle":{"description":"its @handle, once its owner picks one","type":"string"},"id":{"type":"string"},"keys":{"description":"ids of the agent's own proxy keys","items":{"type":"string"},"type":"array"},"name":{"type":"string"},"owner_user_id":{"description":"the person answerable for what it spends","type":"string"},"paused_at":{"format":"date-time","nullable":true,"type":"string"},"paused_reason":{"type":"string"},"picture":{"description":"an id from Lens's gallery: cobalt, orchid, sky, mint, lemon, rose, lime, shopper, grocer, bills, saver, coder, designer, writer, social, recruiter, legal, analyst, events, chef, coach, home, driver, tutor, musician, photographer or gardener. It sets the colour","type":"string"},"pots_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"role":{"description":"what it does: research, sales, bookkeeping, ads, travel, support or other; empty for an agent made before kinds","type":"string"},"role_word":{"description":"what it does in its owner's own word, with role other","maxLength":40,"type":"string"},"spent_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"verified":{"type":"boolean"}},"type":"object"},"AgentApproval":{"properties":{"agent_id":{"type":"string"},"amount_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"approved_by_agent_id":{"description":"the approver agent that approved it within its own limits (B45.28); absent when the owner did","type":"string"},"asks_above_minor":{"description":"the amount its rules ask above, in rules_currency's minor units, when it was filed","format":"int64","nullable":true,"type":"integer"},"asks_above_ulxc":{"description":"the approval amount it was above, when it was filed","format":"int64","nullable":true,"type":"integer"},"budget_left_after_minor":{"description":"the monthly limit less the month's spend and this amount, in rules_currency's minor units, when it was filed; null with no monthly limit","format":"int64","nullable":true,"type":"integer"},"budget_left_after_ulxc":{"description":"the monthly limit less the month's spend and this amount, when it was filed; null with no monthly limit","format":"int64","nullable":true,"type":"integer"},"created_at":{"format":"date-time","type":"string"},"decided_at":{"format":"date-time","nullable":true,"type":"string"},"deny_reason":{"description":"what the owner wrote when declining it, up to 200 characters (B55.18); absent when none","type":"string"},"expires_at":{"description":"When it stops being usable: 24 hours after it was filed while pending, 24 hours after the tap once approved.","format":"date-time","type":"string"},"id":{"type":"string"},"memo":{"type":"string"},"model":{"type":"string"},"paid_from":{"description":"What pays it (B57.11); null on an approval filed before this was kept.","nullable":true,"properties":{"account_id":{"description":"the agent (lxc), the money account, the workspace (marketplace_bill) or the card","type":"string"},"amount_minor":{"description":"the amount in that currency's minor units (µLXC for LXC)","format":"int64","type":"integer"},"balance_minor":{"description":"its balance now, in the same units; null for a bill or a card","format":"int64","nullable":true,"type":"integer"},"currency":{"description":"LXC, USD, EUR, GBP or USDC","type":"string"},"kind":{"enum":["lxc","account","marketplace_bill","card"],"type":"string"},"name":{"description":"in words, e.g. Research’s US dollar account","type":"string"}},"type":"object"},"payee":{"nullable":true,"properties":{"id":{"type":"string"},"kind":{"enum":["agent","listing","company","merchant"],"type":"string"},"name":{"type":"string"}},"type":"object"},"reason":{"type":"string"},"rules_currency":{"description":"the currency the agent's rules were held in when it was filed: GBP, EUR, USD or USDC; empty on one filed before it was kept","type":"string"},"status":{"enum":["pending","approved","denied","used","expired"],"type":"string"}},"type":"object"},"AgentApprover":{"properties":{"agent_id":{"type":"string"},"approver_agent_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"limit_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"mandate":{"description":"the owner's AP2 v0.2 open Payment Mandate, an SD-JWT","type":"string"},"signed_by":{"type":"string"}},"type":"object"},"AgentBook":{"properties":{"agents":{"items":{"$ref":"#/components/schemas/Agent"},"type":"array"},"all_paused_at":{"format":"date-time","nullable":true,"type":"string"},"all_paused_reason":{"type":"string"},"allocated_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"spent_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"unallocated_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"workspace_balance_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"}},"type":"object"},"AgentMoneyPayment":{"description":"A payment from an agent's currency account to another agent's account in the same currency (B61.18): one money entry of two postings.","properties":{"amount_minor":{"description":"in the currency's minor units","format":"int64","type":"integer"},"created_at":{"format":"date-time","type":"string"},"currency":{"enum":["GBP","EUR","USD","USDC"],"type":"string"},"from_account_id":{"type":"string"},"from_agent_id":{"type":"string"},"funding":{"type":"string"},"id":{"description":"the money entry","type":"string"},"idempotency_key":{"type":"string"},"memo":{"type":"string"},"to_account_id":{"type":"string"},"to_agent_id":{"type":"string"},"to_agent_name":{"type":"string"},"to_workspace_id":{"type":"string"},"workspace_id":{"type":"string"}},"type":"object"},"AgentPayment":{"properties":{"amount_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"entry_id":{"type":"string"},"from_agent_id":{"type":"string"},"from_balance_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"memo":{"type":"string"},"to_agent_id":{"type":"string"},"to_balance_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"to_workspace_id":{"type":"string"},"via":{"description":"marketplace: on the company's monthly marketplace bill","type":"string"}},"type":"object"},"AgentRuleBoost":{"properties":{"created_at":{"format":"date-time","type":"string"},"created_by":{"description":"the credential that set it; empty when unknown","type":"string"},"raised_from":{"description":"the limit as the rules set it when the boost was set; once the rules change it, the boost no longer applies","format":"int64","minimum":1,"type":"integer"},"rule":{"description":"the limit raised, as AgentRules names it","enum":["approval_above_ulxc","daily_limit_ulxc","hourly_limit_ulxc","max_per_request_ulxc","monthly_limit_ulxc","requests_per_minute","weekly_limit_ulxc"],"type":"string"},"until":{"description":"from this time on the boost is not read and the limit is the rules' again","format":"date-time","type":"string"},"value":{"description":"what it is raised to: µLXC, or requests a minute for requests_per_minute","format":"int64","minimum":1,"type":"integer"}},"type":"object"},"AgentRules":{"additionalProperties":false,"description":"Zero or empty means no limit. A field this schema does not name is refused (400), so a misspelt rule is never silently no rule.","properties":{"active_from":{"description":"HH:MM in timezone; with active_until, the hours it may spend","example":"09:00","type":"string"},"active_until":{"description":"exclusive; earlier than active_from crosses midnight","example":"18:00","type":"string"},"allowed_currencies":{"description":"the currencies it may convert between, the one sold and the one bought, of GBP, EUR, USD and USDC; empty allows any. Absent keeps the stored list","items":{"type":"string"},"type":"array"},"allowed_listings":{"description":"marketplace listings it may use; empty allows any","items":{"type":"string"},"type":"array"},"allowed_merchant_categories":{"description":"Merchants and categories: the merchant categories it may pay in by card, each one of software, hosting, freight, advertising, travel, telecoms and gambling, or a four-digit merchant category code; once it names any, a card payment in another, or where the merchant reports none, is refused and posts nothing. Absent keeps the stored list","example":["software","hosting","freight"],"items":{"type":"string"},"type":"array"},"allowed_models":{"items":{"type":"string"},"type":"array"},"allowed_payees":{"description":"the ids of the agents, listings, companies (a company names its agents and listings) and card merchants it may pay; once it names any, a payment to another is refused. Absent keeps the stored list","items":{"type":"string"},"type":"array"},"allowed_providers":{"items":{"type":"string"},"type":"array"},"approval_above_ulxc":{"description":"a request that could cost more waits for a person's approval","format":"int64","type":"integer"},"blocked_merchant_categories":{"description":"the merchant categories it may never pay in by card, named as allowed_merchant_categories names them; a card payment in one, or where the merchant reports none, is refused and posts nothing. Absent keeps the stored list","items":{"type":"string"},"type":"array"},"blocked_payees":{"description":"the ids of the payees it may not pay; a payment to one is refused and posts nothing. Absent keeps the stored list","items":{"type":"string"},"type":"array"},"daily_limit_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"fx_daily_limit_minor":{"description":"the most it may convert in a day, in timezone, in minor units of the rules' currency: what it sells in that currency on its own amount, in another at the conversion provider's rate, rounded up; 0 is no limit. Absent keeps the stored maximum","format":"int64","type":"integer"},"fx_daily_limit_ulxc":{"description":"the most it may convert in a day, in timezone, valued as its payments are; 0 is no limit. Absent keeps the stored maximum","format":"int64","type":"integer"},"hourly_limit_ulxc":{"description":"the clock hour, in timezone; absent keeps the stored cap","format":"int64","type":"integer"},"max_per_request_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"model_daily_limits_ulxc":{"additionalProperties":{"format":"int64","type":"integer"},"description":"a model, named as the agent asks for it, to what the agent may spend on it in a day, in timezone; absent keeps the stored caps","type":"object"},"monthly_limit_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"pause_on_unusual_spend":{"type":"boolean"},"payee_allowances":{"additionalProperties":{"$ref":"#/components/schemas/PayeeAllowance"},"description":"the owner's \"always allow\": by payee id, what the agent may pay that payee in a day or a month without approval; past it, a payment above approval_above_ulxc waits for approval again. Absent keeps the stored allowances; saved, it replaces them whole","type":"object"},"payee_daily_limits_minor":{"additionalProperties":{"format":"int64","type":"integer"},"description":"minor units of the rules' currency it may pay one payee in a day, by the payee's id; a payment in that currency is judged on its own amount, one in another at the conversion provider's rate, rounded up. payee_daily_limits_ulxc is what each is worth in LXC. Absent keeps the stored caps; saved, it replaces them whole","type":"object"},"payee_daily_limits_ulxc":{"additionalProperties":{"format":"int64","type":"integer"},"description":"µLXC it may pay one payee in a day, by the payee's id as the payee lists name it (a company's counts its agents and listings); a payment past it is refused and posts nothing. Absent keeps the stored caps; saved, it replaces them whole","type":"object"},"payee_monthly_limits_minor":{"additionalProperties":{"format":"int64","type":"integer"},"description":"payee_daily_limits_minor over the month, in timezone. Absent keeps the stored caps; saved, it replaces them whole","type":"object"},"payee_monthly_limits_ulxc":{"additionalProperties":{"format":"int64","type":"integer"},"description":"payee_daily_limits_ulxc over the month, in timezone. Absent keeps the stored caps; saved, it replaces them whole","type":"object"},"requests_per_minute":{"description":"the requests to models it may make in any sixty seconds; one more is refused 429 and holds nothing. Absent keeps the stored cap","type":"integer"},"timezone":{"description":"IANA name; UTC when empty","example":"Europe/Berlin","type":"string"},"weekly_limit_ulxc":{"description":"the week from Monday, in timezone; absent keeps the stored cap","format":"int64","type":"integer"}},"type":"object"},"AgentRulesVersion":{"properties":{"change":{"description":"set, template \u003cid\u003e, rollback to \u003cn\u003e, or before history for rules set before versions were kept","type":"string"},"changed_by":{"description":"the credential that changed them: operator, or its method, user and key (jwt:user:…); empty when unknown","type":"string"},"created_at":{"format":"date-time","type":"string"},"rules":{"$ref":"#/components/schemas/AgentRules"},"version":{"minimum":1,"type":"integer"}},"type":"object"},"AgentStatementLine":{"properties":{"amount_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"at":{"format":"date-time","type":"string"},"balance_after_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"counterparty":{"description":"workspace | spend | agent:\u003cid\u003e","type":"string"},"entry_id":{"type":"string"},"kind":{"enum":["fund","withdraw","spend","hold","settle","release","pay","platform_fee"],"type":"string"},"label":{"description":"on a platform_fee line, the fee and its rate: \"Platform fee 3%\"","type":"string"},"model":{"description":"on a call's lines (spend, hold, settle, release, platform_fee): the model it asked","type":"string"},"ref":{"description":"a payment's memo, or the request it paid for","type":"string"},"source":{"description":"on a call's lines: where its answer came from; absent until Lens has recorded it","enum":["Model provider","Cache","Shared pool","Node"],"type":"string"}},"type":"object"},"AgentSummary":{"properties":{"agent":{"$ref":"#/components/schemas/Agent"},"all_paused_at":{"description":"set while every agent of the workspace is paused","format":"date-time","type":"string"},"approvals":{"description":"its requests waiting for approval, newest first","items":{"$ref":"#/components/schemas/AgentApproval"},"type":"array"},"as_of":{"description":"the one moment every figure is read at","format":"date-time","type":"string"},"card":{"properties":{"currency":{"type":"string"},"last4":{"type":"string"},"last_declined":{"nullable":true,"properties":{"amount_minor":{"format":"int64","type":"integer"},"at":{"format":"date-time","type":"string"},"currency":{"type":"string"},"merchant_name":{"type":"string"},"reason":{"description":"the reason as it was recorded","type":"string"},"words":{"description":"why, in words: \"Declined: not one of its payees\"","type":"string"}},"type":"object"},"status":{"enum":["none","active","frozen"],"type":"string"}},"type":"object"},"currency_accounts":{"description":"its currency accounts, each with balance_minor","items":{"type":"object"},"type":"array"},"made_at":{"format":"date-time","type":"string"},"month":{"properties":{"currency":{"description":"the currency its rules are held in","type":"string"},"end":{"format":"date-time","type":"string"},"forecast_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"monthly_limit_minor":{"description":"in currency's minor units; 0 is no limit","format":"int64","type":"integer"},"monthly_limit_ulxc":{"description":"µLXC; 0 is no limit","format":"int64","type":"integer"},"runs_out_at":{"format":"date-time","nullable":true,"type":"string"},"runs_out_on":{"format":"date","nullable":true,"type":"string"},"spent_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"start":{"format":"date-time","type":"string"}},"type":"object"},"owner_user_id":{"description":"who made it, which the apps name from the session","type":"string"},"rules":{"description":"the version in force; null when its rules were never set","nullable":true,"properties":{"saved_at":{"format":"date-time","type":"string"},"version":{"minimum":1,"type":"integer"}},"type":"object"},"safe_to_spend":{"description":"LXC (µLXC) first, then GBP, EUR, USD (minor units)","items":{"properties":{"balance":{"format":"int64","type":"integer"},"bills_due":{"format":"int64","type":"integer"},"currency":{"type":"string"},"pending_approvals":{"format":"int64","type":"integer"},"safe_to_spend":{"format":"int64","type":"integer"},"scheduled":{"format":"int64","type":"integer"}},"type":"object"},"type":"array"},"statement":{"description":"its statement's three newest lines this month, by model and day","items":{"$ref":"#/components/schemas/AgentStatementLine"},"type":"array"},"statement_time_zone":{"description":"the zone its days are counted in: its rules', else UTC","type":"string"}},"type":"object"},"AgentTransfer":{"properties":{"amount_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"class":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"entry_id":{"type":"string"},"from_agent_id":{"type":"string"},"from_workspace_id":{"type":"string"},"id":{"type":"string"},"memo":{"type":"string"},"refund_of":{"type":"string"},"request_id":{"type":"string"},"schedule_id":{"type":"string"},"to_agent_id":{"type":"string"},"to_workspace_id":{"type":"string"}},"type":"object"},"HealthStatus":{"properties":{"checks":{"additionalProperties":true,"type":"object"},"database_pool":{"description":"admin key only","properties":{"canceled_waits":{"description":"acquires that gave up waiting","type":"integer"},"idle":{"type":"integer"},"in_use":{"type":"integer"},"max":{"type":"integer"},"wait_count":{"description":"acquires that found no idle connection and waited","type":"integer"},"wait_ms":{"description":"total time those acquires waited","type":"integer"}},"type":"object"},"requests":{"description":"admin key only","properties":{"in_flight":{"description":"requests being served, not counting this probe","type":"integer"},"long_lived":{"description":"of those, subscriptions meant to stay open (SSE)","type":"integer"},"slowest_5m":{"description":"the slowest request of the last five minutes, finished or still running; route template only, never a path","nullable":true,"properties":{"ms":{"type":"integer"},"phase":{"enum":["handler","db_acquire","db_query","redis","upstream"],"type":"string"},"route":{"type":"string"},"running":{"type":"boolean"}},"type":"object"}},"type":"object"},"status":{"enum":["healthy","degraded","unhealthy"],"type":"string"},"uptime_seconds":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"LocalEndpoint":{"properties":{"active":{"type":"boolean"},"avg_latency_ms":{"type":"integer"},"error_rate":{"type":"number"},"healthy":{"type":"boolean"},"id":{"type":"string"},"max_concurrent":{"type":"integer"},"models":{"items":{"type":"string"},"type":"array"},"priority":{"type":"integer"},"provider":{"enum":["ollama","vllm","llamacpp"],"type":"string"},"url":{"type":"string"}},"type":"object"},"PaginatedResponse":{"properties":{"data":{"items":{},"type":"array"},"has_next":{"type":"boolean"},"has_prev":{"type":"boolean"},"next_cursor":{"nullable":true,"type":"string"},"page":{"example":1,"type":"integer"},"page_size":{"example":20,"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}},"type":"object"},"PayeeAllowance":{"properties":{"amount_minor":{"description":"minor units of the rules' currency","format":"int64","minimum":1,"type":"integer"},"amount_ulxc":{"description":"what amount_minor is worth in LXC; sent alone, it is moved to dollars at the peg, and refused on rules in another currency","format":"int64","minimum":1,"type":"integer"},"per":{"enum":["day","month"],"type":"string"}},"required":["per"],"type":"object"},"PendingApproval":{"description":"A request above the agent's approval amount, held for the workspace's owner (B58.2): nothing was paid. Retry it once the owner approves approval_id.","properties":{"amount_ulxc":{"description":"µLXC (1 LXC = 1,000,000 µLXC = $0.10)","format":"int64","type":"integer"},"approval_id":{"type":"string"},"message":{"type":"string"},"status":{"enum":["pending_approval"],"type":"string"}},"required":["status","approval_id","amount_ulxc","message"],"type":"object"},"RuleTemplate":{"description":"Rules an agent can start from. They name every rule, so applying them replaces the agent's rules whole.","properties":{"id":{"example":"support-bot","type":"string"},"name":{"type":"string"},"rules":{"$ref":"#/components/schemas/AgentRules"},"summary":{"description":"the agent it suits and what its rules do","type":"string"}},"type":"object"},"WorkspaceAPIKey":{"properties":{"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","nullable":true,"type":"string"},"id":{"type":"string"},"key_prefix":{"type":"string"},"name":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"workspace_id":{"type":"string"}},"type":"object"},"WorkspaceConfig":{"properties":{"allowed_models":{"items":{"type":"string"},"type":"array"},"allowed_providers":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"log_level":{"enum":["all","errors","none"],"type":"string"},"monthly_budget":{"type":"number"},"name":{"type":"string"},"rate_limit_rpm":{"type":"integer"},"rate_limit_tpm":{"type":"integer"},"retention_days":{"type":"integer"},"spending_cap_usd":{"type":"number"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"Lens API key — Authorization: Bearer tlv_...","scheme":"bearer","type":"http"}}},"info":{"contact":{"name":"Talyvor","url":"https://talyvor.com"},"description":"Agent Wallets and the gateway that enforces them. Every AI agent gets a wallet — a balance, spending rules, approvals, a card and a live statement — and Lens judges each model call and payment against that wallet before it reaches the provider or the payee. Underneath: multi-provider routing with cost tracking, quality scoring and tenant isolation.","title":"Talyvor Lens API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/healthz":{"get":{"description":"Public callers get status, version, uptime_seconds and each check's status and latency_ms. A check's detail and the database_pool and requests sections are shown only with the admin key, the same credential /metrics needs. 503 when a dependency is down.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}},"description":"service health"}},"security":[],"summary":"Liveness + dependency probe"}},"/v1/api/keys":{"post":{"responses":{"410":{"description":"retired; names the route that replaced it"}},"summary":"Retired: the workspace's owner mints a key with explicit scopes with POST /v1/workspaces/{wsID}/api-keys"}},"/v1/api/keys/{keyID}":{"delete":{"parameters":[{"in":"path","name":"keyID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"revoked"}},"summary":"Revoke a Lens admin API key"}},"/v1/audio/speech":{"post":{"description":"JSON {\"input\": \"…\" (up to 4,096 characters), \"model\" (aura-2, the default, tts-1 or tts-1-hd), \"voice\", \"response_format\" (mp3, the default, opus, aac, flac or wav)}. Answers the audio. Charged per character at the model's catalog price. 503 when speech is not configured.","requestBody":{"content":{"application/json":{"schema":{"properties":{"input":{"type":"string"},"model":{"type":"string"},"response_format":{"type":"string"},"voice":{"type":"string"}},"required":["input"],"type":"object"}}},"required":true},"responses":{"200":{"description":"the spoken audio"},"402":{"description":"the wallet, budget or an agent's rules do not cover it"},"503":{"description":"speech is not configured"}},"summary":"Speak text aloud"}},"/v1/audio/transcriptions":{"post":{"description":"multipart/form-data: file (the audio, up to 25 MB), model (nova-3, the default, or whisper-1), and optionally language and response_format (json, the default, or text). Charged per minute heard at the model's catalog price, from the agent's wallet for an agent's key. Lens keeps no audio. 503 when speech is not configured; 402 when the wallet or budget does not cover the clip.","requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"format":"binary","type":"string"},"language":{"type":"string"},"model":{"type":"string"},"response_format":{"enum":["json","text"],"type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"description":"{\"text\": \"…\"}, or the text alone for response_format=text"},"402":{"description":"the wallet, budget or an agent's rules do not cover it"},"503":{"description":"speech is not configured"}},"summary":"Transcribe audio to text"}},"/v1/documents":{"post":{"description":"The request body is the file (up to 25 MB) and its Content-Type the document's media type: PDF, Word, Excel, PowerPoint, HTML, CSV, JSON, XML, Markdown or plain text; ?filename= optionally names it. A chat request then references the returned id instead of carrying the file — {\"type\":\"document\",\"source\":{\"type\":\"file\",\"file_id\":\"tdoc_…\"}} (Anthropic) or {\"type\":\"file\",\"file\":{\"file_id\":\"tdoc_…\"}} (OpenAI) — and Lens converts it to text on the way to the model, reporting the saving in X-Talyvor-Distill-Tokens-Saved and X-Talyvor-Distill-Bytes-Saved. Only the uploading workspace can reference a document. A document over 25 MB is refused with 413, a Content-Type Lens cannot read with 415.","parameters":[{"in":"query","name":"filename","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"required":true},"responses":{"201":{"description":"the stored document: id, media_type, filename, size_bytes, uploaded_at"}},"summary":"Upload a document for chats to reference by id"}},"/v1/local/endpoints":{"get":{"description":"admin key only","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/LocalEndpoint"},"type":"array"}}},"description":"list of endpoints"},"401":{"description":"admin credentials required"}},"summary":"List registered local-model endpoints"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalEndpoint"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalEndpoint"}}}}},"summary":"Register a local-model endpoint"}},"/v1/local/endpoints/{id}":{"delete":{"responses":{"200":{"description":"removed"}},"summary":"Remove a local endpoint"}},"/v1/local/endpoints/{id}/check":{"post":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalEndpoint"}}}}},"summary":"Trigger an immediate health probe for one endpoint"}},"/v1/proxy/anthropic/{path}":{"post":{"parameters":[{"in":"path","name":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"proxied response"}},"summary":"Proxy to Anthropic"}},"/v1/proxy/openai/{path}":{"post":{"description":"Routes OpenAI-shape chat / completions / embeddings through Lens.","parameters":[{"in":"path","name":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"proxied response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"error"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}},"description":"error"}},"summary":"Proxy to OpenAI"}},"/v1/public/fees":{"get":{"description":"No key needed. Basis points (100 = 1%) unless named minor units: market_take_bps (listing sales; the seller keeps the rest), services_take_bps, compute_take_bps, lending_fee_bps, merchant_fee_bps, merchant_a2a_fee_bps, and by plan platform_fee_bps and fx_margin_bps; intl_payment_fee_minor by currency; scan_alert_ulxc, the µLXC of credits a Scan agent pays for each alert its watch sends. charged says, by the same names, whether Lens charges each fee today.","responses":{"200":{"description":"every fee setting"}},"security":[],"summary":"Get every fee Talyvor charges"}},"/v1/public/labels":{"get":{"description":"No key needed. labels: each money capability's label, live or sandbox, worked out on every request: a GREEN capability is live while card payments are live, an AMBER or RED one while it has a clearance in force and every rail its money moves on is live. card_payments (live, test or off) and updated_at.","responses":{"200":{"description":"labels, card_payments, updated_at"}},"security":[],"summary":"Get whether each money feature is Live or Sandbox"}},"/v1/public/plan-gates":{"get":{"description":"No key needed. order (free, team, business, enterprise) and, by plan, agents and seats (-1 unlimited), own_provider_keys (none, add_on — only with the BYOK add-on — or included), live_money, slack_teams_approvals, sso, audit_export and edge. plus, pro and max take free's; byok takes team's, with own keys. built says, by the same names, whether Lens enforces each gate today.","responses":{"200":{"description":"order and plans"}},"security":[],"summary":"Get what each plan unlocks"}},"/v1/wallets/{address}":{"get":{"description":"Who a wallet id or @handle is.","parameters":[{"in":"path","name":"address","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"the wallet's agent and company"},"404":{"description":"no such wallet"}},"summary":"Look up a wallet before sending to it","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents":{"get":{"description":"Each agent's balance and spend, reconciled with the workspace's own balance.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBook"}}},"description":"the agents and the workspace's totals"}},"summary":"List the workspace's agents and their wallets","tags":["Agent Wallets"]},"post":{"description":"Owner or admin. The signed-in person owns the agent; an admin credential names the owner in owner_user_id. With template, the agent starts with exactly that rule template's rules, and the answer carries template and rules too. Without colour or face, Lens picks them from the agent's id, the next free pair when another live agent of the workspace wears that one. A picture sets the colour; role is what it does, and role other names it in role_word.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"colour":{"enum":["cobalt","orchid","sky","mint","lemon","rose","lime"],"type":"string"},"face":{"enum":["circle","squircle","hexagon","flower"],"type":"string"},"name":{"type":"string"},"owner_user_id":{"type":"string"},"picture":{"description":"an id from Lens's gallery: cobalt, orchid, sky, mint, lemon, rose, lime, shopper, grocer, bills, saver, coder, designer, writer, social, recruiter, legal, analyst, events, chef, coach, home, driver, tutor, musician, photographer or gardener. It sets the colour","type":"string"},"role":{"description":"what it does; other names it in role_word","enum":["research","sales","bookkeeping","ads","travel","support","other"],"type":"string"},"role_word":{"description":"what it does in its owner's own word, with role other","maxLength":40,"type":"string"},"template":{"description":"the id of a rule template to start from","example":"support-bot","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}},"description":"the new agent, balance zero"},"400":{"description":"no name, no owner, no such template, or a colour, face, picture or role not on its list"}},"summary":"Create an agent","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/approvals":{"get":{"description":"Newest first. A payment's approval names its payee and memo.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"approvals":{"items":{"$ref":"#/components/schemas/AgentApproval"},"type":"array"}},"type":"object"}}},"description":"the approvals"}},"summary":"List the requests the agents' rules sent to a person","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/approvals/{approvalID}/approve":{"post":{"description":"Owner or admin. The agent's retry of the same request then goes through. Once the workspace has a passkey, the body carries {\"assertion\": {credential_id, client_data_json, authenticator_data, signature}} over the approval's challenge; approving with always_allow, over the challenge asked for with that same always_allow, which the signature covers. With always_allow, a payment's approval also saves that allowance for its payee on the agent's rules (payee_allowances), and the answer adds the rules as saved.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"approvalID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"always_allow":{"$ref":"#/components/schemas/PayeeAllowance"},"assertion":{"type":"object"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApproval"}}},"description":"the approval, approved"},"400":{"description":"always_allow without an amount above 0 and per day or month"},"403":{"description":"a passkey assertion is required, or it is invalid"},"404":{"description":"no such approval"},"409":{"description":"approved once, but always_allow was not saved: the approval names no payee"}},"summary":"Approve a request, once — or approve it and always allow its payee","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/approvals/{approvalID}/deny":{"post":{"description":"Owner or admin; signed with a passkey the same way as approve. reason, optional and up to 200 characters, is kept on the approval as deny_reason and told to the agent. Until the approval life (24 hours) after the decline, the agent's identical request is refused naming the decline and its reason, without filing a new approval or telling the owner again; a different request asks at once.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"approvalID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"assertion":{"type":"object"},"reason":{"maxLength":200,"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApproval"}}},"description":"the approval, denied"},"400":{"description":"a reason over 200 characters"},"403":{"description":"a passkey assertion is required, or it is invalid"},"404":{"description":"no such approval"}},"summary":"Deny a request","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/approvals/{approvalID}/evidence":{"get":{"description":"The owner's signed approval as an AP2 v0.2 closed Payment Mandate (an SD-JWT, owner_mandate), or an approver agent's approval as Talyvor-signed evidence naming both agents (agent_evidence, a JWS) with the open mandate it ran under (approver_mandate). Both verify with the key at jwks_url; docs/ap2-mandates.md is the format.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"approvalID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"agent_evidence":{"type":"string"},"approval_id":{"type":"string"},"approved_by_agent_id":{"type":"string"},"approver_mandate":{"type":"string"},"jwks_url":{"type":"string"},"owner_mandate":{"type":"string"}},"type":"object"}}},"description":"the evidence"},"404":{"description":"no such approval"}},"summary":"Read what proves an approval","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/pause-all":{"post":{"description":"Owner or admin. Those created later included, until resume-all.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"reason":{"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"description":"paused"}},"summary":"Pause every agent in the workspace","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/resume-all":{"post":{"description":"Owner or admin. Lifts pause-all; an agent paused on its own stays paused. Once the workspace has a passkey or device key, it takes an assertion over the resume-all challenge.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"assertion":{"type":"object"}},"type":"object"}}},"required":false},"responses":{"200":{"description":"resumed"},"403":{"description":"no assertion, or one Lens could not verify: every agent stays paused"}},"summary":"Resume every agent in the workspace","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/resume-all/challenge":{"post":{"description":"Owner or admin. Single use, for five minutes.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"the challenge and the passkeys that may sign it"}},"summary":"Get the challenge resuming every agent is signed over","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/rule-templates":{"get":{"description":"Support bot, Researcher and Coder: each names every rule, so applying one replaces an agent's rules whole.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"templates":{"items":{"$ref":"#/components/schemas/RuleTemplate"},"type":"array"}},"type":"object"}}},"description":"the templates"}},"summary":"List the rule templates an agent can start from","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/statement":{"get":{"description":"For the period [from, to), as JSON, CSV, PDF or a journal for an accounting package — the statement an auditor can open. kind and q keep only the lines that match, and limit pages them newest first, each page with the whole period's totals and a next_cursor.","parameters":[{"in":"query","name":"limit","required":false,"schema":{"maximum":1000,"minimum":1,"type":"integer"}},{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"description":"RFC 3339 time or YYYY-MM-DD (midnight UTC); defaults to the start of this month","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"exclusive; RFC 3339 time or YYYY-MM-DD; defaults to now","in":"query","name":"to","required":false,"schema":{"type":"string"}},{"description":"json (the default), csv, pdf: the statement as a document to download, its opening and closing balances the JSON's, or journal: a CSV of double-entry journal lines (journal_no, date, account, description, debit_lxc, credit_lxc, cost_centre, ref) for Xero or QuickBooks, one journal per entry, each balanced, its cost centre the entry's agent, the statement's accounts' debits their in_ulxc and credits their out_ulxc. The CSV, the PDF and the journal are one row per posting, never grouped, filtered or paged","in":"query","name":"format","required":false,"schema":{"enum":["json","csv","pdf","journal"],"type":"string"}},{"description":"day: each model's questions on a day one line (model, requests, total), its platform fee the line under it; days in the agent's rules' time_zone, else UTC (the workspace's: UTC). The CSV is never grouped","in":"query","name":"group","required":false,"schema":{"enum":["day"],"type":"string"}},{"description":"the next_cursor of the page before, with that page's to and the same kind and q; pages are newest first","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"only lines of these kinds, comma-separated (fund, withdraw, spend, hold, settle, release, pay, card, platform_fee, ...); the totals stay the whole period's. The CSV is never filtered","in":"query","name":"kind","required":false,"schema":{"type":"string"}},{"description":"only lines whose kind, account, counterparty, ref, memo, label, model or entry holds this text, in any case; at most 200 characters","in":"query","name":"q","required":false,"schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"the period statement"}},"summary":"Read the statement of every agent wallet in the workspace","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}":{"patch":{"description":"Owner or admin. Any of the fields; a name cannot be blank, a description is at most 500 characters, and a colour, face, picture or role is one on its list. A picture sets the colour, and a colour without one takes its colour's picture; role_word comes only with role other.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"colour":{"enum":["cobalt","orchid","sky","mint","lemon","rose","lime"],"type":"string"},"description":{"type":"string"},"face":{"enum":["circle","squircle","hexagon","flower"],"type":"string"},"name":{"type":"string"},"picture":{"description":"an id from Lens's gallery: cobalt, orchid, sky, mint, lemon, rose, lime, shopper, grocer, bills, saver, coder, designer, writer, social, recruiter, legal, analyst, events, chef, coach, home, driver, tutor, musician, photographer or gardener. It sets the colour","type":"string"},"role":{"description":"what it does; other names it in role_word","enum":["research","sales","bookkeeping","ads","travel","support","other"],"type":"string"},"role_word":{"description":"what it does in its owner's own word, with role other","maxLength":40,"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}},"description":"the agent"},"400":{"description":"a blank name, a description too long, a colour, face, picture or role not on its list, or an unknown field"},"404":{"description":"no such agent"}},"summary":"Rename, describe or change the face of the agent","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/analytics":{"get":{"description":"For the period [from, to) of its statement: every posting that took money out of the agent's account is in one bucket, so the buckets' out_ulxc sum to the statement's. returned_ulxc is a hold's unused part coming back, on the day it came back; spent_ulxc is out less returned. Days are in the agent's rules' time_zone, else UTC. destination is the account the money went to, as the statement's counterparty names it.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}},{"description":"RFC 3339 time or YYYY-MM-DD (midnight UTC); defaults to the start of this month","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"exclusive; RFC 3339 time or YYYY-MM-DD; defaults to now","in":"query","name":"to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"string"},"buckets":{"items":{"properties":{"day":{"type":"string"},"destination":{"type":"string"},"model":{"type":"string"},"out_ulxc":{"format":"int64","type":"integer"},"postings":{"format":"int64","type":"integer"},"returned_ulxc":{"format":"int64","type":"integer"},"spent_ulxc":{"format":"int64","type":"integer"}},"type":"object"},"type":"array"},"out_ulxc":{"format":"int64","type":"integer"},"returned_ulxc":{"format":"int64","type":"integer"},"spent_ulxc":{"format":"int64","type":"integer"},"time_zone":{"type":"string"}},"type":"object"}}},"description":"the agent's spend in buckets"},"400":{"description":"from or to is not a time, or from is not before to"},"404":{"description":"no such agent"}},"summary":"Read the agent's spend by day, model and destination","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/approvals/{approvalID}/approve":{"post":{"description":"By the approver agent's own key only. Approved when the amount is within the lower of the approver's limit when the owner signed and its limit now, and within its daily limit over what it approved today; above them it is 409 and the request waits for the owner.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}},{"in":"path","name":"approvalID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApproval"}}},"description":"the approval, approved"},"403":{"description":"not the approver's own key, not the approver in force, or the approver is paused"},"404":{"description":"no such pending approval"},"409":{"description":"above the approver's own limits: it waits for the owner"}},"summary":"Approve another agent's request, as its approver","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/approver":{"delete":{"description":"Owner or admin, at once and unsigned. From then on the agent's requests go to the owner.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"removed"},"404":{"description":"no approver"}},"summary":"Take the approver away","tags":["Agent Wallets"]},"get":{"description":"The approver in force, its limit and the owner's AP2 v0.2 open Payment Mandate that set it.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApprover"}}},"description":"the approver"},"404":{"description":"no approver: its requests go to the owner"}},"summary":"Read the agent that approves this agent's requests","tags":["Agent Wallets"]},"put":{"description":"Owner or admin, signed on the Talyvor app: {\"approver_agent_id\", \"assertion\"} over the challenge (a passkey or a device key). Kept as an AP2 v0.2 open Payment Mandate bound to the approver's Agent Card key; it replaces the approver in force. A request above the approver's limits still goes to the owner.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"approver_agent_id":{"type":"string"},"assertion":{"type":"object"}},"required":["approver_agent_id","assertion"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApprover"}}},"description":"the approver"},"400":{"description":"the agent itself, an archived agent, or one with no limit of its own"},"403":{"description":"no signature, or one that does not verify"},"404":{"description":"no such agent"}},"summary":"Let an agent approve this agent's requests, within its own limits","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/approver/challenge":{"post":{"description":"Owner or admin. Also the limit the approver would approve up to: its own, the lower of its max_per_request_ulxc and approval_above_ulxc. An approver with neither may approve nothing.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"approver_agent_id":{"type":"string"}},"required":["approver_agent_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"challenge":{"type":"string"},"limit_ulxc":{"format":"int64","minimum":1,"type":"integer"},"user_verification":{"type":"string"}},"type":"object"}}},"description":"the challenge"},"400":{"description":"the agent itself, an archived agent, or one with no limit of its own"},"404":{"description":"no such agent"}},"summary":"Get the challenge to sign to let an agent approve this agent's requests","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/archive":{"post":{"description":"Owner or admin. In one step: the agent's whole balance goes back to the workspace as one withdraw, its proxy keys are revoked, its top-up and schedules stop. It stays listed, with archived_at, and its statement is kept; it can no longer be funded or move money of its own.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"string"},"archived_at":{"format":"date-time","type":"string"},"revoked_keys":{"items":{"type":"string"},"type":"array"},"swept_ulxc":{"format":"int64","type":"integer"}},"type":"object"}}},"description":"what archiving did"},"404":{"description":"no such agent"},"409":{"description":"already archived, or LXC is still kept in its pots"}},"summary":"Archive the agent","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/card":{"get":{"description":"Newest first, approved and declined; each authorisation was decided by the agent's rules and balance.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"the card and its authorisations"}},"summary":"Read the agent's card and its authorisations","tags":["Agent Wallets"]},"post":{"description":"Owner or admin; the agent's owner is the cardholder. With a live Stripe key it is 409 and nothing is issued: cards take no real money until a licensed partner issues them.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"phone_number":{"type":"string"},"postal_code":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"201":{"description":"the card"},"409":{"description":"a live Stripe key, or the agent already has a card — no card is issued"}},"summary":"Issue the agent a virtual card","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/card/draws-on":{"post":{"description":"Owner or admin. credits: the agent's credits. account: the agent's currency account in the card's currency, which must be open; each purchase is judged by the agent's rules and held on the account until it is captured, reversed or refunded.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"draws_on":{"type":"string"}},"required":["draws_on"],"type":"object"}}},"required":true},"responses":{"200":{"description":"the card"},"400":{"description":"draws_on is neither credits nor account"},"404":{"description":"no such agent, or it holds no card"},"409":{"description":"the agent has no open account in the card's currency"}},"summary":"Choose what the agent's card spends","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/card/freeze":{"post":{"description":"Owner or admin. Every purchase on a frozen card is declined and nothing leaves the agent.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"the card, frozen"},"404":{"description":"no such agent, or it holds no card"}},"summary":"Freeze the agent's card","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/card/unfreeze":{"post":{"description":"Owner or admin. Purchases are judged by the agent's rules and balance again.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"the card, unfrozen"},"404":{"description":"no such agent, or it holds no card"}},"summary":"Unfreeze the agent's card","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/fund":{"post":{"description":"Owner or admin.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}},{"description":"sent again with the same key, the move lands once (at most 128 characters)","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"amount_ulxc":{"format":"int64","minimum":1,"type":"integer"}},"required":["amount_ulxc"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"string"},"balance_ulxc":{"format":"int64","minimum":1,"type":"integer"}},"type":"object"}}},"description":"the agent's balance after the move"},"404":{"description":"no such agent"},"409":{"description":"the workspace cannot cover it, or the agent has no owner"}},"summary":"Fund the agent from the workspace's credit","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/keys":{"post":{"description":"Owner or admin. The agent calls its models through /v1/proxy/… with this key, and every request on it is judged against the agent's wallet. The raw key is shown once.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"defaults to the agent's id","type":"string"}},"type":"object"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"string"},"id":{"type":"string"},"key":{"type":"string"},"prefix":{"type":"string"},"warning":{"type":"string"}},"type":"object"}}},"description":"the key, shown once"},"404":{"description":"no such agent in this workspace"}},"summary":"Issue the agent a proxy key of its own","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/pause":{"post":{"description":"Owner or admin. Every movement of the agent is refused until it is resumed, effective on its next request, buffered or streamed.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"reason":{"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"description":"paused"}},"summary":"Pause the agent","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/pay":{"post":{"description":"By the agent's own key, a connected assistant, the workspace's owner or an admin. With amount_minor and currency it pays from the agent's account in that currency into the other agent's account in the same currency, in this workspace or another, under the Idempotency-Key, which it needs: one entry, on both accounts' statements (AgentMoneyPayment). Nothing is converted: an agent with no account in the currency is refused 409. The agent's rules judge it like any other spend. Above the agent's approval amount it is held for the owner: 202, nothing is paid, and the same request goes through once the owner approves.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}},{"description":"sent again with the same key, the move lands once (at most 128 characters)","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"amount_minor":{"description":"with currency: the amount in its minor units","format":"int64","type":"integer"},"amount_ulxc":{"format":"int64","minimum":1,"type":"integer"},"currency":{"enum":["GBP","EUR","USD","USDC"],"type":"string"},"funding":{"enum":["test","live"],"type":"string"},"memo":{"type":"string"},"to_agent_id":{"description":"an agent id or @handle","type":"string"}},"required":["to_agent_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AgentMoneyPayment"},{"$ref":"#/components/schemas/AgentPayment"}]}}},"description":"the payment: AgentMoneyPayment in a currency, AgentPayment in credits"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApproval"}}},"description":"held for the owner's approval"},"403":{"description":"not the agent's key, the owner or an admin — or a rule refused it"},"404":{"description":"no such agent, or no account in the currency to pay from"},"409":{"description":"the agent's balance cannot cover it, the agent paid has no account in the currency, money of a kind a workspace does not hold (code wrong_money_kind), or the Idempotency-Key was used for another payment"}},"summary":"Pay another agent","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/resume":{"post":{"description":"Owner or admin. Once the workspace has a passkey or device key, it takes an assertion over the resume challenge.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"assertion":{"type":"object"}},"type":"object"}}},"required":false},"responses":{"200":{"description":"resumed"},"403":{"description":"no assertion, or one Lens could not verify: the agent stays paused"}},"summary":"Resume a paused agent","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/resume/challenge":{"post":{"description":"Owner or admin. Single use, for five minutes.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"the challenge and the passkeys that may sign it"},"404":{"description":"no such agent"}},"summary":"Get the challenge resuming the agent is signed over","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/rules":{"get":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRules"}}},"description":"the rules"},"404":{"description":"no such agent"}},"summary":"Read the agent's spending rules","tags":["Agent Wallets"]},"put":{"description":"Owner or admin. Lens judges every model call, payment and card purchase of the agent against these before it happens: a request a rule refuses is answered 403 naming the rule and never reaches the provider.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRules"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRules"}}},"description":"the rules as stored"},"400":{"description":"an unknown field or an invalid rule"},"404":{"description":"no such agent"}},"summary":"Replace the agent's spending rules","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/rules/boosts":{"get":{"description":"The limits raised for now, the soonest to end first. A boost that has ended is not listed: the limit is the rules' again.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"boosts":{"items":{"$ref":"#/components/schemas/AgentRuleBoost"},"type":"array"}},"type":"object"}}},"description":"the boosts in force"},"404":{"description":"no such agent"}},"summary":"List the agent's temporary limit boosts in force","tags":["Agent Wallets"]},"post":{"description":"Owner or admin. Until the time, the limit is the boost's value; from then on the rules judge it as the rules set it, with nothing to undo. The limit must be set and the value above it, and the boost applies only while the rules leave the limit as it was. A boost replaces the one the limit had.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"rule":{"enum":["approval_above_ulxc","daily_limit_ulxc","hourly_limit_ulxc","max_per_request_ulxc","monthly_limit_ulxc","requests_per_minute","weekly_limit_ulxc"],"type":"string"},"until":{"format":"date-time","type":"string"},"value":{"format":"int64","minimum":1,"type":"integer"}},"required":["rule","value","until"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRuleBoost"}}},"description":"the boost"},"400":{"description":"an unknown limit, a limit not set, a value not above it, or a time not in the future"},"404":{"description":"no such agent"}},"summary":"Raise one of the agent's limits until a time","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/rules/boosts/{rule}":{"delete":{"description":"Owner or admin. The limit is the rules' again at once.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}},{"in":"path","name":"rule","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"ended"},"404":{"description":"no such agent, or no boost in force on that limit"}},"summary":"End a limit boost before its time","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/rules/history":{"get":{"description":"Newest first: the first is the rules in force. Every change that alters the rules — a save, a template, a rollback — is a version, with who made it.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"versions":{"items":{"$ref":"#/components/schemas/AgentRulesVersion"},"type":"array"}},"type":"object"}}},"description":"the versions"},"404":{"description":"no such agent"}},"summary":"List the versions of the agent's rules","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/rules/rollback":{"post":{"description":"Owner or admin. The rules become exactly what they were at version — a rule added since keeps its value — and the rollback is itself a new version, recording who made it.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"version":{"minimum":1,"type":"integer"}},"required":["version"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRules"}}},"description":"the rules now in force"},"400":{"description":"no version given"},"404":{"description":"no such agent, or no such version"}},"summary":"Roll the agent's rules back to an earlier version","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/rules/simulate":{"post":{"description":"Moves nothing: the rules judge the request exactly as a real one, against what the agent has really spent, and everything the judgement would write is rolled back — no posting, no approval filed. With payee it is a payment to that payee; without, a question to model through provider. at (RFC 3339) asks about another time, for the active hours and the periods; now when absent. always_allow, with payee, judges the payment as though that allowance for its payee were saved: the preview of approving with always allow.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"always_allow":{"$ref":"#/components/schemas/PayeeAllowance"},"amount_ulxc":{"format":"int64","minimum":0,"type":"integer"},"at":{"format":"date-time","type":"string"},"model":{"type":"string"},"payee":{"properties":{"id":{"type":"string"},"kind":{"enum":["agent","listing","company","merchant"],"type":"string"}},"required":["kind","id"],"type":"object"},"provider":{"type":"string"}},"required":["amount_ulxc"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"amount_ulxc":{"format":"int64","type":"integer"},"at":{"format":"date-time","type":"string"},"balance_ulxc":{"description":"what the agent holds now, which the rules do not judge","format":"int64","type":"integer"},"reason":{"description":"why it is refused or needs approval; empty when allowed","type":"string"},"verdict":{"enum":["allowed","refused","approval_required"],"type":"string"}},"required":["verdict","reason","amount_ulxc","at","balance_ulxc"],"type":"object"}}},"description":"the rules' answer"},"400":{"description":"an unknown field, a negative amount or a payee of no known kind"},"404":{"description":"no such agent"}},"summary":"Ask whether the agent's rules would let a request through","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/rules/template":{"post":{"description":"Owner or admin. Replaces every one of the agent's rules with the template's: the agent then holds exactly the template, nothing kept from before.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"template":{"example":"researcher","type":"string"}},"required":["template"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRules"}}},"description":"the rules as stored"},"400":{"description":"no such template"},"404":{"description":"no such agent"}},"summary":"Apply a rule template to the agent","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/send":{"post":{"description":"By the agent's own key, the workspace's owner or an admin. The agent's rules judge it like any other spend.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"amount_ulxc":{"format":"int64","minimum":1,"type":"integer"},"memo":{"type":"string"},"to":{"description":"a wallet id or @handle","type":"string"}},"required":["to","amount_ulxc"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTransfer"}}},"description":"the transfer"},"403":{"description":"not the agent's key, the owner or an admin — or a rule refused it"},"409":{"description":"the agent's balance cannot cover it"}},"summary":"Send credits to any agent on Talyvor","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/statement":{"get":{"description":"With none of from, to, format, group, cursor, kind or q: the agent's account, newest first (limit, default and at most 1000). With any of them: the statement for the period [from, to), as JSON, CSV, PDF or a journal for an accounting package; kind and q keep only the lines that match, then limit pages them newest first, each page with the whole period's totals and a next_cursor.","parameters":[{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"maximum":1000,"minimum":1,"type":"integer"}},{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"description":"RFC 3339 time or YYYY-MM-DD (midnight UTC); defaults to the start of this month","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"exclusive; RFC 3339 time or YYYY-MM-DD; defaults to now","in":"query","name":"to","required":false,"schema":{"type":"string"}},{"description":"json (the default), csv, pdf: the statement as a document to download, its opening and closing balances the JSON's, or journal: a CSV of double-entry journal lines (journal_no, date, account, description, debit_lxc, credit_lxc, cost_centre, ref) for Xero or QuickBooks, one journal per entry, each balanced, its cost centre the entry's agent, the statement's accounts' debits their in_ulxc and credits their out_ulxc. The CSV, the PDF and the journal are one row per posting, never grouped, filtered or paged","in":"query","name":"format","required":false,"schema":{"enum":["json","csv","pdf","journal"],"type":"string"}},{"description":"day: each model's questions on a day one line (model, requests, total), its platform fee the line under it; days in the agent's rules' time_zone, else UTC (the workspace's: UTC). The CSV is never grouped","in":"query","name":"group","required":false,"schema":{"enum":["day"],"type":"string"}},{"description":"the next_cursor of the page before, with that page's to and the same kind and q; pages are newest first","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"only lines of these kinds, comma-separated (fund, withdraw, spend, hold, settle, release, pay, card, platform_fee, ...); the totals stay the whole period's. The CSV is never filtered","in":"query","name":"kind","required":false,"schema":{"type":"string"}},{"description":"only lines whose kind, account, counterparty, ref, memo, label, model or entry holds this text, in any case; at most 200 characters","in":"query","name":"q","required":false,"schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"string"},"lines":{"items":{"$ref":"#/components/schemas/AgentStatementLine"},"type":"array"}},"type":"object"}}},"description":"the agent's lines"},"404":{"description":"no such agent"}},"summary":"Read the agent's statement","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/summary":{"get":{"description":"Owner or admin. Every figure is read in one transaction at one moment, as_of: the agent's balance less what waits for approval is its safe-to-spend figure. Another workspace's agent is 404.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSummary"}}},"description":"the agent's page"},"403":{"description":"not the workspace's owner or an admin"},"404":{"description":"no such agent"}},"summary":"Read one agent's page in one read","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/transfers":{"get":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"transfers":{"items":{"$ref":"#/components/schemas/AgentTransfer"},"type":"array"}},"type":"object"}}},"description":"the transfers"}},"summary":"List what the agent sent and received","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/agents/{agentID}/withdraw":{"post":{"description":"Owner or admin.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"agentID","required":true,"schema":{"type":"string"}},{"description":"sent again with the same key, the move lands once (at most 128 characters)","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"amount_ulxc":{"format":"int64","minimum":1,"type":"integer"}},"required":["amount_ulxc"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"string"},"balance_ulxc":{"format":"int64","minimum":1,"type":"integer"}},"type":"object"}}},"description":"the agent's balance after the move"},"404":{"description":"no such agent"},"409":{"description":"the agent's balance cannot cover it"}},"summary":"Move credit from the agent back to the workspace","tags":["Agent Wallets"]}},"/v1/workspaces/{wsID}/api-keys":{"get":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/WorkspaceAPIKey"},"type":"array"}}},"description":"list of keys"}},"summary":"List workspace-scoped API keys"},"post":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"key created — raw key shown exactly once"}},"summary":"Issue a workspace-scoped API key"}},"/v1/workspaces/{wsID}/api-keys/{keyID}":{"delete":{"responses":{"200":{"description":"revoked"}},"summary":"Revoke a workspace-scoped API key"}},"/v1/workspaces/{wsID}/approval-chat":{"delete":{"description":"Owner or admin only (403). 404 when none is saved.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"removed"}},"summary":"Disconnect Slack or Teams"},"get":{"description":"{\"on\": the plan includes Slack and Teams approvals, \"hook\": {\"kind\",\"host\",\"updated_at\"} or null}. The webhook's URL is never returned. Present only when the deployment holds custody (LENS_PROVIDER_SECRET_KEK).","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"on, hook"}},"summary":"The Slack or Teams webhook this workspace's approvals are posted to"},"put":{"description":"Body {\"kind\":\"slack\" or \"teams\",\"url\":\"\u003cincoming webhook\u003e\"}. Owner or admin only (403). A URL that is not a Slack or Teams webhook is refused (400); a plan without Slack and Teams approvals is refused in words (402). Nothing posted there decides an approval: that is done in Talyvor with the passkey. Answers with the kind and host only.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kind, host, updated_at"}},"summary":"Connect Slack or Teams: each approval filed is posted there with a button that opens it in Talyvor"}},"/v1/workspaces/{wsID}/config":{"get":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceConfig"}}}}},"summary":"Get workspace tenant config"},"put":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceConfig"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceConfig"}}}}},"summary":"Upsert workspace tenant config"}},"/v1/workspaces/{wsID}/deletion-requests":{"get":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"requests: id, status (requested|done), requested_at, completed_at"}},"summary":"List this workspace's deletion requests and their status"},"post":{"description":"Body {\"note\":\"…\"} (optional). An operator completes the request; billing and ledger records are kept, as the law requires.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"the request, status requested"}},"summary":"Ask Talyvor to delete everything it holds for this workspace"}},"/v1/workspaces/{wsID}/name":{"get":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"id, name"}},"summary":"Get this workspace's name"},"put":{"description":"The workspace's owner only. Body {\"name\"}: trimmed, 1 to 80 characters. The change is recorded in the audit trail.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"id, name"},"400":{"description":"the name is empty, longer than 80 characters or has control characters"},"403":{"description":"not the workspace's owner"}},"summary":"Name this workspace"}},"/v1/workspaces/{wsID}/plan":{"get":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"plan, gated_as, byok_add_on, gates, own_provider_keys_allowed, agents_used"}},"summary":"Get this workspace's plan and what it unlocks"}},"/v1/workspaces/{wsID}/plan/seats":{"get":{"description":"Asked before a member is added, with the count the workspace would have. 402 says it in words, with the setting (LENS_PLAN_GATES), the plan and the plan that would allow it as fields.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"query","name":"members","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"plan, seats, members"},"402":{"description":"error, plan, gate, limit, allows"}},"summary":"Check whether this workspace's plan takes a number of members"}},"/v1/workspaces/{wsID}/provider-keys":{"get":{"description":"{\"byok\": on the BYOK plan, \"providers\": the providers a key can be added for, \"keys\": [{\"provider\",\"last4\",\"updated_at\"}]}. The key itself is never returned. Present only when the deployment holds custody (LENS_PROVIDER_SECRET_KEK).","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"byok, providers, keys"}},"summary":"List this workspace's own provider keys (BYOK) — the last four characters only"}},"/v1/workspaces/{wsID}/provider-keys/{provider}":{"delete":{"description":"404 when no key is stored for that provider.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"provider","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"removed"}},"summary":"Remove this workspace's own key for a provider (BYOK)"},"put":{"description":"Body {\"key\":\"…\"}. Requests to that provider are then sent on this key and charged no tokens. Refused (402) unless the workspace is on the BYOK plan; an unknown provider or a malformed key is refused (400). Answers with the provider and last four characters only.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"provider","required":true,"schema":{"enum":["anthropic","google","groq","mistral","openai"],"type":"string"}}],"responses":{"200":{"description":"provider, last4, updated_at"}},"summary":"Add or replace this workspace's own key for a provider (BYOK)"}},"/v1/workspaces/{wsID}/savings/current-month":{"get":{"description":"Summed over the workspace's own requests this calendar month (UTC): what each would have cost at the model it asked for with no Talyvor cache (list_usd), minus what it was charged (charged_usd). Requests recorded without a measurement are counted in unmeasured_requests and left out of the sums.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"month_start, saved_usd, list_usd, charged_usd, requests, unmeasured_requests"}},"summary":"Get this month's measured saving for a workspace"}},"/v1/workspaces/{wsID}/spend/current-month":{"get":{"responses":{"200":{"description":"spend snapshot"}},"summary":"Get current-month spend for a workspace"}},"/v1/workspaces/{wsID}/sso":{"delete":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"removed"}},"summary":"Remove this workspace's single sign-on connection and its domains"},"get":{"description":"{\"issuer\",\"client_id\",\"domains\":[{\"domain\",\"record\",\"value\",\"proven_at\"}],\"updated_at\"}. A domain counts once a TXT record named record answers value. The owner, signed in, only. 404 when there is none. Present only when the deployment holds custody (LENS_PROVIDER_SECRET_KEK).","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"the connection"}},"summary":"Get this workspace's single sign-on connection — never its client secret"},"put":{"description":"Body {\"issuer\":\"https://…\",\"client_id\",\"client_secret\",\"domains\":[\"example.com\"]}. The secret is sealed and never returned. A domain kept from the connection it replaces stays proven; a new one starts unproven. Refused (402) unless the plan includes single sign-on; 409 when another workspace has proven a domain.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"the connection"}},"summary":"Save this workspace's single sign-on connection"}},"/v1/workspaces/{wsID}/sso/domains/{domain}/check":{"post":{"description":"200 with the domain, proven. 409 with {\"error\",\"domain\"} while the TXT record does not answer the value yet, or when another workspace has proven the domain.","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}},{"in":"path","name":"domain","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"domain, record, value, proven_at"}},"summary":"Check a domain's TXT record and prove it for this workspace's single sign-on"}},"/v1/workspaces/{wsID}/stored-answers":{"delete":{"description":"Body {\"scope\":\"shared\"|\"all\",\"confirm\":\"\u003cworkspace\u003e\"}. \"shared\" deletes every answer and document conversion this workspace shared; \"all\" also deletes its private ones. Earnings already final are kept. A confirm that does not match the workspace is refused (400); a caller that is not the owner or an admin is refused (403).","parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"what was deleted, as counts"}},"summary":"Delete this workspace's stored answers — irreversible, owner or admin only"},"get":{"parameters":[{"in":"path","name":"wsID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"shared_answers, private_answers, shared_conversions, private_conversions, cached_copies"}},"summary":"Count this workspace's stored answers and document conversions, by scope"}}},"security":[{"ApiKeyAuth":[]}],"servers":[{"description":"current deployment","url":"/"}],"tags":[{"description":"Every AI agent gets a wallet — a balance, spending rules, approvals, a card and a live statement. The agent calls its models through Lens with a key of its own, and Lens judges each request and payment against its wallet before the provider or the payee sees it. Amounts are in µLXC: 1 LXC = 1,000,000 µLXC = $0.10, so $1 is 10000000.","name":"Agent Wallets"}]}
