{"openapi":"3.1.0","info":{"title":"TermWorks Agent API","version":"1.0.0","description":"TermWorks is a developer opportunity network. Sponsors pay to display contextual messages in developers' terminals; developers earn a 50% share of every impression. This API lets AI agents query audience reach and launch campaigns — no signup required, pay per call with USDC on Tempo.","x-guidance":"Use POST /api/v1/mpp/audience to estimate how many developers match your targeting before spending — send a JSON body with optional 'categories' (array), 'seniority' (array), and 'open_to_work' (boolean) fields. Use POST /api/v1/mpp/campaigns to launch a campaign once you have a TermWorks advertiser_id with funded account balance. Use PATCH /api/v1/mpp/campaigns/:id to edit a pending_review or paused campaign. Use POST /api/v1/mpp/topup to top up an advertiser account balance with USDC — pay on-chain first, then submit the tx_hash. All payment endpoints require payment via HTTP 402 Machine Payments Protocol (MPP) on Tempo. Pay with USDC. Campaigns start in pending_review and go live within 24 hours.","contact":{"email":"hello@term.works"}},"x-discovery":{"ownershipProofs":[]},"paths":{"/api/v1/mpp/audience":{"post":{"operationId":"getAudienceEstimate","summary":"Audience Estimate — reach count for given targeting parameters","tags":["Discovery"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"mpp":{"method":"tempo","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}]},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"},"description":"Developer categories to target. Options: infra, backend, frontend, ai-ml, mobile, web3, devops, data, security","example":["backend","infra"]},"seniority":{"type":"array","items":{"type":"string"},"description":"Seniority levels to target. Options: junior, mid, senior, staff, principal","example":["senior","staff"]},"open_to_work":{"type":"boolean","description":"Filter to developers actively open to job opportunities","example":true}}}}}},"responses":{"200":{"description":"Estimated developer reach for the given targeting","content":{"application/json":{"schema":{"type":"object","properties":{"estimated_reach":{"type":"integer","description":"Number of active developer installs matching the targeting"},"filters_applied":{"type":"object","description":"Echo of the filters that were applied"}},"required":["estimated_reach","filters_applied"]}}}},"402":{"description":"Payment Required"}}}},"/api/v1/mpp/campaigns":{"post":{"operationId":"createCampaign","summary":"Create Campaign — launch a developer-targeted ad campaign","tags":["Campaigns"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.500000"},"protocols":[{"mpp":{"method":"tempo","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"advertiser_id":{"type":"string","format":"uuid","description":"TermWorks advertiser account ID (must have funded balance)"},"title":{"type":"string","minLength":1,"maxLength":120,"description":"Campaign headline shown to developers in the terminal"},"message":{"type":"string","minLength":1,"maxLength":280,"description":"Optional longer message. Defaults to title if omitted."},"url":{"type":"string","format":"uri","description":"Destination URL when developer clicks through"},"opportunity_type":{"type":"string","enum":["sponsor","opportunity","role","job"],"default":"sponsor","description":"sponsor=$0.05 min CPM, opportunity=$0.15, role=$0.50, job=$1.00"},"bid_cpm_cents":{"type":"integer","description":"Bid in cents per 1,000 impressions (e.g. 500 = $5 CPM)","minimum":5},"budget_cents":{"type":"integer","description":"Total campaign budget in cents (deducted from account balance)","minimum":100},"targeting":{"type":"object","description":"Optional targeting filters","properties":{"categories":{"type":"array","items":{"type":"string"},"description":"infra, backend, frontend, ai-ml, mobile, web3, devops, data, security"},"seniority_levels":{"type":"array","items":{"type":"string"},"description":"junior, mid, senior, staff, principal"},"open_to_work":{"type":"boolean"},"os":{"type":"array","items":{"type":"string"},"description":"macos, linux, windows"}}},"starts_at":{"type":"string","format":"date-time","description":"Optional campaign start time. Defaults to now."},"ends_at":{"type":"string","format":"date-time","description":"Optional campaign end time. Defaults to never."}},"required":["advertiser_id","title","url","bid_cpm_cents","budget_cents"]}}}},"responses":{"201":{"description":"Campaign created and pending review (goes live within 24h)","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","example":"pending_review"},"bid_cpm_cents":{"type":"integer"},"total_budget_cents":{"type":"integer"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"required":["campaign"]}}}},"402":{"description":"Payment Required"},"402_balance":{"description":"Insufficient account balance — top up at term.works/dashboard before creating campaigns"}}}},"/api/v1/mpp/campaigns/{id}":{"patch":{"operationId":"editCampaign","summary":"Edit Campaign — update targeting, creative, or bid on an existing campaign","tags":["Campaigns"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.500000"},"protocols":[{"mpp":{"method":"tempo","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}]},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Campaign ID to edit"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"advertiser_id":{"type":"string","format":"uuid","description":"Must be the advertiser that owns this campaign"},"title":{"type":"string","maxLength":120},"url":{"type":"string","format":"uri"},"bid_cpm_cents":{"type":"integer","minimum":5},"targeting":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"}},"required_tags":{"type":"array","items":{"type":"string"}},"seniority_levels":{"type":"array","items":{"type":"string"}},"open_to_work":{"type":"boolean"},"os":{"type":"array","items":{"type":"string"}}}}},"required":["advertiser_id"]}}}},"responses":{"200":{"description":"Campaign updated and re-queued for review"},"400":{"description":"Campaign is not in an editable state (must be pending_review or paused)"},"402":{"description":"Payment Required"},"404":{"description":"Campaign not found or does not belong to this advertiser"}}}},"/api/v1/mpp/topup":{"post":{"operationId":"topupAccount","summary":"Top Up Account — credit an advertiser account with USDC paid on Tempo","tags":["Account"],"x-payment-info":{"price":{"mode":"variable","currency":"USD","minimum":"1.00","minPrice":"1.00"},"protocols":[{"mpp":{"method":"tempo","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"advertiser_id":{"type":"string","format":"uuid","description":"TermWorks advertiser account ID to credit"},"tx_hash":{"type":"string","description":"On-chain Tempo transaction hash of the USDC payment to our wallet. Pay first, then submit the hash. The amount paid on-chain is the amount credited."}},"required":["advertiser_id","tx_hash"]}}}},"responses":{"200":{"description":"Account credited successfully","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"credited_cents":{"type":"integer","description":"Amount credited in cents"},"balance_cents":{"type":"integer","description":"New account balance in cents"},"tx_hash":{"type":"string"}}}}}},"202":{"description":"Transaction not yet confirmed — retry in 15 seconds"},"400":{"description":"Payment too small (minimum $1.00) or bad request"},"402":{"description":"No tx_hash provided — pay first, then retry with the hash"},"409":{"description":"This transaction hash has already been used"}}}}}}