{"openapi":"3.1.0","info":{"title":"Physical Agency API","version":"0.1.0","description":"Real-world execution for AI agents. Global human workforce pool for AI agents. The same operations are available as MCP tools at /api/mcp. Read /api/v1/capabilities first."},"servers":[{"url":"https://physical-agency-141382386601.asia-southeast1.run.app"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Client keys start with mpc_, worker keys with mpw_."}}},"paths":{"/api/v1/capabilities":{"get":{"summary":"Service scope, categories, lifecycle, terms and prohibited uses","responses":{"200":{"description":"Capabilities","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"get_capabilities"}},"/api/v1/skills":{"get":{"summary":"Skills, languages, categories and countries in the active pool with counts","responses":{"200":{"description":"Pool stats","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"list_skills"}},"/api/v1/products":{"get":{"summary":"Search consultation-required products; listings do not confirm supply or booking","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"locale","in":"query","required":false,"schema":{"default":"ko","type":"string","enum":["ko","en"]}},{"name":"family","in":"query","required":false,"schema":{"type":"string","enum":["agent_tasks","traditional_staffing"]}},{"name":"group","in":"query","required":false,"schema":{"type":"string","enum":["device_testing","retail_checks","user_research","handoff_errands","onsite_operations","robotics_data","human_evaluation","physical_quality","local_language","place_observation","driving","household","hospitality","cleaning_lodging","logistics","manufacturing","construction","agriculture","events","care","office_facilities","store_staffing"]}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":10000}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Paginated products with nextOffset","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"version":{"type":"string"},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextOffset":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"contentLanguage":{"type":"string","enum":["ko","en"]},"family":{"type":"string","enum":["agent_tasks","traditional_staffing"]},"group":{"type":"string"},"groupName":{"type":"string"},"discoveryTerms":{"type":"string"},"researchRegion":{"type":"string","enum":["KR","various"]},"buyer":{"type":"string"},"work":{"type":"string"},"status":{"type":"string","const":"consultation_required"},"availability":{"type":"string","const":"unconfirmed"}},"required":["id","name","contentLanguage","family","group","groupName","discoveryTerms","researchRegion","buyer","work","status","availability"],"additionalProperties":false}}},"required":["version","total","offset","nextOffset","products"],"additionalProperties":false}}}},"400":{"description":"INVALID_INPUT"},"401":{"description":"Missing/invalid key"},"429":{"description":"Rate limited or quota exceeded"}},"operationId":"list_products"}},"/api/v1/products/{productId}":{"get":{"summary":"Product conditions, completion criteria and consultation guidance","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string","pattern":"^(?:[A-Z]{3}\\d{2}|TRD\\d{3})$"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["ko","en"],"default":"ko"}}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"contentLanguage":{"type":"string","enum":["ko","en"]},"family":{"type":"string","enum":["agent_tasks","traditional_staffing"]},"group":{"type":"string"},"groupName":{"type":"string"},"discoveryTerms":{"type":"string"},"researchRegion":{"type":"string","enum":["KR","various"]},"buyer":{"type":"string"},"work":{"type":"string"},"status":{"type":"string","const":"consultation_required"},"availability":{"type":"string","const":"unconfirmed"},"requestConditions":{"type":"array","items":{"type":"string"}},"completionCriteria":{"type":"string"},"agentNext":{"type":"string"},"consultationChecks":{"type":"array","items":{"type":"string"}},"relatedProductIds":{"type":"array","items":{"type":"string"}},"research":{"type":"object","properties":{"rank":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"score":{"type":["number","null"]},"basis":{"type":"string"},"sourceIds":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["rank","score","basis","sourceIds","note"],"additionalProperties":false},"requestGuide":{"type":"object","properties":{"tool":{"type":"string"},"endpoint":{"type":"string"},"productId":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["tool","endpoint","productId","steps","note"],"additionalProperties":false}},"required":["id","name","contentLanguage","family","group","groupName","discoveryTerms","researchRegion","buyer","work","status","availability","requestConditions","completionCriteria","agentNext","consultationChecks","relatedProductIds","research","requestGuide"],"additionalProperties":false}}}},"400":{"description":"INVALID_INPUT"},"401":{"description":"Missing/invalid key"},"404":{"description":"NOT_FOUND"},"429":{"description":"Rate limited or quota exceeded"}},"operationId":"get_product"}},"/api/v1/workers":{"get":{"summary":"Search anonymous workers (comma-separated lists in query)","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"skills","in":"query","required":false,"schema":{"type":"string"}},{"name":"languages","in":"query","required":false,"schema":{"type":"string"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string"}},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string"}},{"name":"city","in":"query","required":false,"schema":{"type":"string"}},{"name":"minVerification","in":"query","required":false,"schema":{"type":"string"}},{"name":"budgetAmountMinor","in":"query","required":false,"schema":{"type":"string"}},{"name":"budgetCurrency","in":"query","required":false,"schema":{"type":"string"}},{"name":"estimatedMinutes","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ranked workers","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_INPUT"},"401":{"description":"Missing/invalid key"},"429":{"description":"Rate limited or quota exceeded"}},"operationId":"search_workers_query"},"post":{"summary":"Search anonymous workers (JSON body, same as MCP search_workers)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"category":{"type":"string","enum":["research","data_work","writing_translation","software_testing","design_creative","expert_consult","field_check","local_errand","customer_ops","other"]},"skills":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":48,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},"languages":{"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}$"}},"mode":{"default":"remote","type":"string","enum":["remote","onsite"]},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"city":{"type":"string","minLength":1,"maxLength":80},"minVerification":{"type":"string","enum":["unverified","identity_verified","skill_verified"]},"budget":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amountMinor","currency"],"additionalProperties":false},"estimatedMinutes":{"type":"integer","minimum":5,"maximum":43200},"limit":{"default":10,"type":"integer","minimum":1,"maximum":25}},"additionalProperties":false}}}},"responses":{"200":{"description":"Ranked workers","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_INPUT"},"401":{"description":"Missing/invalid key"},"429":{"description":"Rate limited or quota exceeded"}},"operationId":"search_workers"}},"/api/v1/workers/{handle}":{"get":{"summary":"Anonymous worker profile","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string","pattern":"^w-[a-z0-9]{6}$"}}],"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND"}},"operationId":"get_worker_profile"}},"/api/v1/tasks":{"post":{"security":[{"bearer":[]}],"x-role":"client","summary":"Submit a task (not acceptance, quote or payment). Idempotency-Key header accepted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"productId":{"type":"string","pattern":"^(?:[A-Z]{3}\\d{2}|TRD\\d{3})$"},"title":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":6000},"acceptanceCriteria":{"type":"string","minLength":1,"maxLength":2000},"category":{"type":"string","enum":["research","data_work","writing_translation","software_testing","design_creative","expert_consult","field_check","local_errand","customer_ops","other"]},"requiredSkills":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","maxLength":48,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},"languages":{"default":["en"],"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}$"}},"mode":{"default":"remote","type":"string","enum":["remote","onsite"]},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"city":{"type":"string","minLength":1,"maxLength":80},"deadline":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"estimatedMinutes":{"type":"integer","minimum":5,"maximum":43200},"budget":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":0,"maximum":100000000},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amountMinor","currency"],"additionalProperties":false},"preferredWorkers":{"default":[],"maxItems":5,"type":"array","items":{"type":"string","pattern":"^w-[a-z0-9]{6}$"}},"minVerification":{"type":"string","enum":["unverified","identity_verified","skill_verified"]},"acknowledgeHumanReview":{"type":"boolean","const":true},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}},"required":["title","description","acceptanceCriteria","category","acknowledgeHumanReview","idempotencyKey"],"additionalProperties":false}}}},"responses":{"201":{"description":"Task","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_INPUT"},"401":{"description":"Missing/invalid key"},"409":{"description":"IDEMPOTENCY_CONFLICT"},"429":{"description":"Rate limited or quota exceeded"}},"operationId":"submit_task"},"get":{"security":[{"bearer":[]}],"x-role":"client","summary":"List your tasks","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Tasks","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_INPUT"},"401":{"description":"Missing/invalid key"},"429":{"description":"Rate limited or quota exceeded"}},"operationId":"list_tasks"}},"/api/v1/tasks/{id}":{"get":{"security":[{"bearer":[]}],"x-role":"client","summary":"Read your task, timeline and (when completed) result","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Task","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND"}},"operationId":"get_task"}},"/api/v1/tasks/{id}/cancel":{"post":{"security":[{"bearer":[]}],"x-role":"client","summary":"Cancel before a worker starts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"additionalProperties":false}}}},"responses":{"200":{"description":"Task","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"INVALID_TRANSITION / CANCEL_REQUIRES_OPERATOR"}},"operationId":"cancel_task"}},"/api/v1/me":{"get":{"security":[{"bearer":[]}],"x-role":"worker","summary":"Your profile as agents see it","responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"get_my_profile"}},"/api/v1/offers":{"get":{"security":[{"bearer":[]}],"x-role":"worker","summary":"Your offers and accepted work","responses":{"200":{"description":"Offers","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"list_my_offers"}},"/api/v1/offers/{id}/respond":{"post":{"security":[{"bearer":[]}],"x-role":"worker","summary":"Accept or decline an offer","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["accept","decline"]}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Offer","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"OFFER_EXPIRED / INVALID_TRANSITION"}},"operationId":"respond_to_offer"}},"/api/v1/offers/{id}/result":{"post":{"security":[{"bearer":[]}],"x-role":"worker","summary":"Submit result for operator review","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"result":{"type":"string","minLength":1,"maxLength":20000},"spentMinutes":{"type":"integer","minimum":0,"maximum":100000}},"required":["result","spentMinutes"],"additionalProperties":false}}}},"responses":{"200":{"description":"Offer","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"submit_offer_result"}},"/api/v1/applications":{"post":{"summary":"Apply to join the pool (reviewed before listing)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"headline":{"type":"string","minLength":1,"maxLength":160},"legalName":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","maxLength":200,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","maxLength":40},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"city":{"type":"string","minLength":1,"maxLength":80},"timezone":{"type":"string","maxLength":64},"languages":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}$"}},"skills":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"string","maxLength":48,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},"categories":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["research","data_work","writing_translation","software_testing","design_creative","expert_consult","field_check","local_errand","customer_ops","other"]}},"remote":{"type":"boolean"},"onsite":{"type":"boolean"},"hourlyRate":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":0,"maximum":10000000},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amountMinor","currency"],"additionalProperties":false},"hoursPerWeek":{"type":"integer","minimum":1,"maximum":80},"weeklyHours":{"default":[],"maxItems":21,"type":"array","items":{"type":"object","properties":{"day":{"type":"integer","minimum":0,"maximum":6},"start":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"end":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$|^24:00$"}},"required":["day","start","end"],"additionalProperties":false}},"source":{"default":"direct","type":"string","enum":["direct","referral","community","partner","job_board","social","event","other"]},"sourceRef":{"type":"string","minLength":1,"maxLength":200},"consent":{"type":"boolean","const":true},"consentVersion":{"type":"string","const":"2026-10-07"}},"required":["headline","legalName","email","phone","countryCode","timezone","languages","skills","categories","remote","onsite","consent","consentVersion"],"additionalProperties":false}}}},"responses":{"202":{"description":"Received","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_INPUT"},"401":{"description":"Missing/invalid key"},"429":{"description":"Rate limited or quota exceeded"}},"operationId":"submit_application"}}}}