{"openapi":"3.0.3","info":{"title":"Chirp Agent API","version":"1.2.0","description":"Scoped external-agent API for Chirp by SkillChirp: Threads account summaries, personal-baseline performance, Scout, next moves, and confirmation-gated scheduling. API keys resolve exactly one connected Chirp profile and never expose Threads access tokens.","termsOfService":"https://www.skillchirp.com/terms","contact":{"name":"SkillChirp Support","url":"https://www.skillchirp.com/contact","email":"support@skillchirp.com"}},"servers":[{"url":"https://skillchirp.onrender.com"}],"externalDocs":{"description":"Chirp developer reference, security model and revocation guidance","url":"https://www.skillchirp.com/developers/chirp"},"components":{"securitySchemes":{"ChirpApiKey":{"type":"http","scheme":"bearer","bearerFormat":"chirp_live_…","description":"Create a scoped key from Chirp Settings. The raw secret is shown once and can be revoked at any time."}},"schemas":{"ChirpError":{"type":"object","properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}},"paths":{"/api/v1/chirp/account/":{"get":{"summary":"Read the connected Threads account summary","description":"Returns the account bound to this API key. Clients do not supply a Chirp profile id.","tags":["Chirp Agent"],"security":[{"ChirpApiKey":[]}],"x-required-scope":"analytics:read","responses":{"200":{"description":"Account summary"},"401":{"description":"Missing, invalid, revoked or disconnected Chirp API key"},"403":{"description":"The API key does not have the required scope"},"429":{"description":"Per-key rate limit exceeded"}}}},"/api/v1/chirp/performance/":{"get":{"summary":"Read first-party performance and personal baseline","description":"Returns measured performance intelligence derived from the connected Chirp profile.","tags":["Chirp Agent"],"security":[{"ChirpApiKey":[]}],"x-required-scope":"analytics:read","responses":{"200":{"description":"Performance intelligence"},"401":{"description":"Missing, invalid, revoked or disconnected Chirp API key"},"403":{"description":"The API key does not have the required scope"},"429":{"description":"Per-key rate limit exceeded"}}}},"/api/v1/chirp/next-move/":{"get":{"summary":"Get data-backed next moves and saved Scout opportunities","tags":["Chirp Agent"],"security":[{"ChirpApiKey":[]}],"x-required-scope":"recommendations:read","responses":{"200":{"description":"Recommendations and opportunities"},"401":{"description":"Missing, invalid, revoked or disconnected Chirp API key"},"403":{"description":"The API key does not have the required scope"},"429":{"description":"Per-key rate limit exceeded"}}}},"/api/v1/chirp/scout/":{"post":{"summary":"Search Scout for conversations worth joining","description":"Searches configured sources using the connected Chirp profile. Threads access tokens are never returned.","tags":["Chirp Agent"],"security":[{"ChirpApiKey":[]}],"x-required-scope":"scout:read","responses":{"200":{"description":"Scout results"},"401":{"description":"Missing, invalid, revoked or disconnected Chirp API key"},"403":{"description":"The API key does not have the required scope"},"429":{"description":"Per-key rate limit exceeded"}}}},"/api/v1/chirp/schedule/prepare/":{"post":{"summary":"Validate and preview a scheduled Threads post","description":"Creates a short-lived confirmation preview only. It does not create a scheduled post.","tags":["Chirp Agent"],"security":[{"ChirpApiKey":[]}],"x-required-scope":"schedule:write","responses":{"200":{"description":"Confirmation preview and single-use token"},"401":{"description":"Missing, invalid, revoked or disconnected Chirp API key"},"403":{"description":"The API key does not have the required scope"},"429":{"description":"Per-key rate limit exceeded"}}}},"/api/v1/chirp/schedule/confirm/":{"post":{"summary":"Confirm a prepared scheduled Threads post","description":"Consumes a matching, unexpired, single-use confirmation token created for the same account and API key.","tags":["Chirp Agent"],"security":[{"ChirpApiKey":[]}],"x-required-scope":"schedule:write","responses":{"201":{"description":"Scheduled post created"},"409":{"description":"Confirmation expired or already used"},"401":{"description":"Missing, invalid, revoked or disconnected Chirp API key"},"403":{"description":"The API key does not have the required scope"},"429":{"description":"Per-key rate limit exceeded"}}}}},"x-chirp-scopes":{"analytics:read":"Read account and post performance","scout:read":"Search Scout opportunities","recommendations:read":"Read data-backed next moves","schedule:write":"Prepare and confirm scheduled Threads posts. This scope is opt-in and never granted by default."},"x-chirp-security":{"account_binding":"Each API key resolves one connected Chirp profile. External clients do not provide profile ids.","key_storage":"Raw API keys are shown once; SkillChirp stores a SHA-256 digest.","revocation":"Users can revoke an API key from Chirp Settings; revoked keys stop authenticating immediately.","write_boundary":"Scheduling requires the opt-in schedule:write scope plus a separate prepare/confirm flow with a short-lived single-use token.","credential_exposure":"Threads access tokens, billing controls and admin APIs are not exposed by this API.","audit":"External calls are audited without storing raw API keys or Threads access tokens."},"x-error-format":{"error":{"code":"STRING_CODE","message":"Human-readable message","retryable":false}}}