{"openapi":"3.1.0","info":{"title":"Apply Guy Job Application API","version":"1.0.0","summary":"Search live jobs and submit applications with pure HTTP.","description":"The Apply Guy Developer API gives agents and applications a current U.S. job catalog, U.S.-normalized candidate profiles, credit-based job submission, and signed status webhooks. Billable catalog reads require both jobs:read and credits:spend. Job search costs 0.05 credit per requested block of up to 25 results, and a successfully retrieved job detail costs 0.01 credit. Managed applications cost 2 credits. Bring-your-own-agent applications cost 1 credit and pause whenever your agent needs to generate structured answers. Credits are sold at 20 per US dollar. Developer API v1 is U.S.-only; a raw employer URL is caller-selected and should point to a U.S.-appropriate role.","contact":{"name":"Apply Guy developer support","url":"https://applyguy.ai/developers"}},"externalDocs":{"description":"Developer guides and use cases","url":"https://applyguy.ai/developers/docs"},"servers":[{"url":"https://api.applyguy.ai","description":"Production"}],"tags":[{"name":"Setup","description":"Create a developer account and manage API keys."},{"name":"Jobs","description":"Search the fresh Apply Guy job catalog or retrieve one listing. Billable reads require jobs:read and credits:spend; successful requests use fractional credits."},{"name":"Candidate profile","description":"Store the candidate facts and resume used during applications."},{"name":"Integrations","description":"Configure account integrations required by some ATS workflows."},{"name":"Credits","description":"Inspect the balance or purchase credits through hosted Stripe Checkout."},{"name":"Usage","description":"Measure application outcomes, credit economics, latency, and API-key activity or share a read-only report."},{"name":"Applications","description":"Preflight, submit, monitor, and cancel job applications."},{"name":"Agent answers","description":"Complete structured answer rounds in bring-your-own-agent mode."},{"name":"Webhooks","description":"Receive signed application state changes without polling."}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ag_live_…","description":"Developer API key returned once when it is created. Scopes are enforced server-side. Billable job search and detail endpoints require both jobs:read and credits:spend; credits:spend alone grants no catalog access."},"SessionToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Account access token used only to create and revoke developer API keys."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","example":"invalid_request"},"message":{"type":"string","example":"The request could not be processed."},"requestId":{"type":"string","example":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"},"details":{"description":"Optional structured validation or recovery details."}}}}},"ManagementError":{"type":"object","required":["error"],"description":"Error envelope used by account and API-key management routes.","properties":{"error":{"type":"string","example":"invalid_input"},"details":{"description":"Optional structured validation details."},"login":{"type":"string","description":"Login path returned when the email already has an account."},"retryAfter":{"type":"integer","description":"Seconds until a rate-limited request can be retried."}}},"DeveloperScope":{"type":"string","description":"A least-privilege API-key capability. jobs:read permits catalog access; credits:spend separately authorizes a key to incur the documented job-search and job-detail charges. Both are required for billable catalog reads, and credits:spend grants no read access by itself.","enum":["jobs:read","credits:spend","profile:read","profile:write","credits:read","credits:write","applications:read","applications:write","webhooks:write","usage:read","usage:share"]},"DeveloperBootstrap":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"agent-builder@example.com"},"password":{"type":"string","format":"password","minLength":8,"writeOnly":true,"example":"correct-horse-battery-staple"},"name":{"type":"string","default":"Default agent","maxLength":80,"example":"Production agent"},"scopes":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/DeveloperScope"},"example":["jobs:read","credits:spend","profile:read","profile:write","credits:read","credits:write","applications:read","applications:write","webhooks:write","usage:read","usage:share"]},"expiresAt":{"type":"string","format":"date-time","example":"2027-08-23T00:00:00.000Z"}}},"DeveloperBootstrapResult":{"type":"object","required":["user","apiKey","accessToken","refreshToken","credits","next","warning"],"properties":{"user":{"type":"object","required":["id","email","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"createdAt":{"type":"string","format":"date-time"}}},"apiKey":{"type":"object","required":["id","key","prefix","scopes"],"properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string","readOnly":true,"example":"ag_live_7ab4d918f903_••••••••••••••••"},"prefix":{"type":"string","example":"7ab4d918f903"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperScope"}}}},"accessToken":{"type":"string","readOnly":true,"description":"Short-lived account JWT for API-key management."},"refreshToken":{"type":"string","readOnly":true,"description":"Long-lived account token. This is its only response."},"credits":{"type":"number","const":0},"next":{"type":"object","additionalProperties":{"type":"string"}},"warning":{"type":"string","example":"Store the API key and refresh token now. Neither can be retrieved again."}}},"SessionRefresh":{"type":"object","required":["refreshToken"],"properties":{"refreshToken":{"type":"string","writeOnly":true,"description":"The latest refresh token. Refresh tokens rotate on every successful use."}},"additionalProperties":false},"SessionRefreshResult":{"type":"object","required":["accessToken","refreshToken"],"properties":{"accessToken":{"type":"string","readOnly":true},"refreshToken":{"type":"string","readOnly":true,"description":"Replacement refresh token. Atomically replace the token sent in the request."}}},"ApiKeyCreate":{"type":"object","properties":{"name":{"type":"string","default":"Default agent","maxLength":80,"example":"CI application agent"},"scopes":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/DeveloperScope"},"example":["jobs:read","credits:spend","applications:read","applications:write"]},"expiresAt":{"type":"string","format":"date-time","example":"2027-08-23T00:00:00.000Z"}}},"ApiKey":{"type":"object","required":["id","name","prefix","scopes","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","example":"7ab4d918f903"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperScope"}},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ApiKeyCreated":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","required":["key","warning"],"properties":{"key":{"type":"string","readOnly":true,"example":"ag_live_7ab4d918f903_••••••••••••••••"},"warning":{"type":"string","example":"Store this key now. It cannot be retrieved again."}}}],"description":"API-key metadata plus the one-time plaintext secret returned only on creation."},"EmailIntegrationCreate":{"type":"object","required":["gmailUser","gmailAppPassword"],"properties":{"gmailUser":{"type":"string","format":"email","example":"candidate@gmail.com"},"gmailAppPassword":{"type":"string","minLength":16,"maxLength":19,"writeOnly":true,"description":"A 16-character Gmail app password. Spaces are accepted and removed before validation; this is not the Gmail account password.","example":"abcd efgh ijkl mnop"}},"additionalProperties":false},"EmailIntegrationStatus":{"type":"object","required":["emailIntegration"],"properties":{"emailIntegration":{"type":"object","required":["configured","requiredAts"],"properties":{"configured":{"type":"boolean"},"requiredAts":{"type":"array","items":{"type":"string"},"example":["workday"]}}}}},"JobSummary":{"type":"object","required":["id","title","company","ats","url","country"],"properties":{"id":{"type":"string","format":"uuid","example":"951f7024-bbf7-4aa5-98fc-f45625584f9b"},"title":{"type":"string","example":"Software Engineer"},"company":{"type":"string","example":"Example Labs"},"companySlug":{"type":["string","null"],"example":"example-labs"},"ats":{"type":"string","example":"greenhouse"},"url":{"type":"string","format":"uri","example":"https://boards.greenhouse.io/example/jobs/123456"},"location":{"type":["string","null"],"example":"New York, NY"},"city":{"type":["string","null"],"example":"New York"},"state":{"type":["string","null"],"example":"New York"},"country":{"type":"string","const":"US","example":"US","description":"Developer API v1 exposes U.S. catalog jobs only."},"remoteType":{"type":["string","null"],"enum":["remote","hybrid","onsite",null]},"employmentType":{"type":["string","null"],"example":"full-time"},"salaryMin":{"type":["number","null"],"example":120000},"salaryMax":{"type":["number","null"],"example":165000},"salaryCurrency":{"type":["string","null"],"example":"USD"},"postedAt":{"type":["string","null"],"format":"date-time"},"firstSeenAt":{"type":["string","null"],"format":"date-time"},"canonicalTitle":{"type":["string","null"],"example":"Software Engineer"},"roleFamily":{"type":["string","null"],"example":"software_engineering"},"skills":{"type":["array","null"],"items":{"type":"string"},"example":["TypeScript","PostgreSQL"]},"minimumExperienceYears":{"type":["number","null"],"minimum":0,"example":2},"maximumExperienceYears":{"type":["number","null"],"minimum":0,"example":5},"educationLevel":{"type":["string","null"],"example":"bachelors"},"sponsorship":{"type":["string","null"],"example":"not_available"},"clearanceRequired":{"type":["boolean","null"],"example":false}}},"JobDetail":{"allOf":[{"$ref":"#/components/schemas/JobSummary"},{"type":"object","properties":{"descriptionHtml":{"type":["string","null"],"description":"Employer-provided job description HTML."},"descriptionSections":{"type":["object","array","null"],"description":"Parsed description sections when available."},"specialties":{"type":["array","null"],"items":{"type":"string"}},"requiredSkills":{"type":["array","null"],"items":{"type":"string"}},"clearanceLabel":{"type":["string","null"]},"travelPercent":{"type":["number","null"],"minimum":0,"maximum":100}}}]},"Address":{"type":"object","required":["line1","city","state","postalCode","country"],"properties":{"line1":{"type":"string","maxLength":500,"example":"501 Delancey Street"},"line2":{"type":"string","maxLength":500,"example":"Apt 4B"},"city":{"type":"string","maxLength":500,"example":"San Francisco"},"state":{"type":"string","maxLength":500,"description":"Full state or region name.","example":"California"},"postalCode":{"type":"string","maxLength":30,"example":"94107"},"country":{"type":"string","maxLength":500,"description":"Full country descriptor. Candidate normalization is U.S.-centric in v1.","example":"United States of America"},"county":{"type":"string","maxLength":500,"example":"San Francisco County"}},"additionalProperties":false},"WorkHistoryEntry":{"type":"object","required":["company","title","startDate"],"properties":{"company":{"type":"string","maxLength":500},"title":{"type":"string","maxLength":500},"startDate":{"type":"string","maxLength":7,"example":"2024-01"},"endDate":{"type":"string","maxLength":7,"example":"2026-08"},"current":{"type":"boolean"},"location":{"type":"string","maxLength":500},"summary":{"type":"string","maxLength":10000},"highlights":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":2000}}},"additionalProperties":false},"EducationEntry":{"type":"object","required":["school","city","state"],"properties":{"school":{"type":"string","maxLength":500},"city":{"type":"string","maxLength":500},"state":{"type":"string","maxLength":500},"degree":{"type":"string","maxLength":500},"discipline":{"type":"string","maxLength":500},"startDate":{"type":"string","maxLength":7},"endDate":{"type":"string","maxLength":7},"gpa":{"type":"string","maxLength":30}},"additionalProperties":false},"WorkAuthorization":{"type":"object","required":["country","status","requiresSponsorship"],"properties":{"country":{"type":"string","minLength":2,"maxLength":2,"example":"US"},"status":{"type":"string","enum":["citizen","permanent-resident","work-visa","requires-sponsorship","student-visa","other"]},"requiresSponsorship":{"type":"boolean"}},"additionalProperties":false},"LegalDeclarations":{"type":"object","properties":{"hasActiveNonCompete":{"type":"boolean"},"legalWorkCountries":{"type":"array","maxItems":50,"items":{"type":"string","minLength":2,"maxLength":2}}},"additionalProperties":false},"WorkPreferences":{"type":"object","properties":{"remotePreference":{"type":"string","enum":["remote","hybrid","onsite","flexible"]},"willingToRelocate":{"type":"boolean"},"willingToCommuteDaysPerWeek":{"type":"integer","minimum":0,"maximum":7},"salaryRangeUsd":{"type":"object","required":["min","max"],"properties":{"min":{"type":"number","minimum":0},"max":{"type":"number","minimum":0}},"additionalProperties":false},"notes":{"type":"string","maxLength":10000}},"additionalProperties":false},"Demographics":{"type":"object","properties":{"defaultDisclosure":{"type":"string","enum":["share","decline"]},"gender":{"type":"string","maxLength":500},"ethnicity":{"type":"string","maxLength":500},"hispanicOrLatino":{"type":"boolean"},"veteranStatus":{"type":"string","enum":["veteran","not-veteran","prefer-not-to-say"]},"militaryStatus":{"type":"string","enum":["none","active-duty","reserve","national-guard","veteran","prefer-not-to-say"]},"disabilityStatus":{"type":"string","enum":["yes","no","prefer-not-to-say"]},"transgender":{"type":"boolean"},"lgbtq":{"type":"boolean"}},"additionalProperties":false},"CandidateContext":{"type":"object","description":"Candidate facts used to fill employer forms. PUT merges supplied properties into the stored profile.","properties":{"firstName":{"type":"string","maxLength":500,"example":"Jordan"},"lastName":{"type":"string","maxLength":500,"example":"Bamber"},"email":{"type":"string","maxLength":320,"example":"jordan@example.com"},"phone":{"type":"string","maxLength":40,"example":"+1 415 555 0199"},"location":{"type":"string","maxLength":500,"example":"San Francisco, CA"},"address":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"linkedin":{"type":"string","maxLength":2048,"example":"https://www.linkedin.com/in/jordan-bamber"},"website":{"type":"string","maxLength":2048},"github":{"type":"string","maxLength":2048,"example":"https://github.com/jordan"},"portfolio":{"type":"string","maxLength":2048},"resumeText":{"type":"string","maxLength":100000,"description":"Extracted resume text used for open-ended answers."},"workHistory":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/WorkHistoryEntry"}},"education":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/EducationEntry"}},"skills":{"type":"array","maxItems":500,"items":{"type":"string","maxLength":500},"example":["TypeScript","PostgreSQL","AWS"]},"yearsOfExperience":{"type":"object","additionalProperties":{"type":"number","minimum":0,"maximum":100}},"bio":{"type":"string","maxLength":20000},"motivations":{"type":"string","maxLength":20000},"discoverySource":{"type":"string","maxLength":500,"example":"internet"},"workAuthorization":{"$ref":"#/components/schemas/WorkAuthorization"},"legalDeclarations":{"$ref":"#/components/schemas/LegalDeclarations"},"workPreferences":{"$ref":"#/components/schemas/WorkPreferences"},"demographics":{"$ref":"#/components/schemas/Demographics"}},"additionalProperties":false},"ApplicationCreate":{"type":"object","oneOf":[{"required":["jobId"]},{"required":["jobUrl"]}],"properties":{"jobId":{"type":"string","format":"uuid","description":"A job returned by the catalog.","example":"951f7024-bbf7-4aa5-98fc-f45625584f9b"},"jobUrl":{"type":"string","format":"uri","maxLength":2048,"description":"A supported platform-owned HTTPS employer application URL for a caller-selected U.S.-appropriate role. Raw URL availability is resolved during application execution.","example":"https://boards.greenhouse.io/example/jobs/123456"},"ats":{"type":"string","minLength":1,"maxLength":50,"description":"Optional ATS hint when submitting a URL. It must agree with the URL host.","example":"greenhouse"},"mode":{"type":"string","enum":["managed","agent"],"default":"managed","description":"Managed costs 2 credits. Agent mode costs 1 credit and requests structured answers from your agent."}}},"ApplicationStatus":{"type":"string","description":"Applications in agent mode can enter awaiting_answers one or more times.","enum":["queued","running","awaiting_answers","success","failed","cancelled"]},"ApplicationOutcomeCode":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]*$","description":"Stable, public failure classification. Known codes are job_no_longer_available, invalid_job_url, profile_missing, resume_missing, email_integration_required, captcha_failed, application_input_required, submission_outcome_unknown, already_applied, application_limit_reached, and application_failed. New codes may be added without a version bump; branch on known values and keep an unknown fallback.","examples":["job_no_longer_available","invalid_job_url","profile_missing","resume_missing","email_integration_required","captcha_failed","application_input_required","submission_outcome_unknown","already_applied","application_limit_reached","application_failed"]},"ApplicationOutcomeDetails":{"type":["object","null"],"description":"Structured metadata for an outcome code when available. For application_limit_reached, maxApplications and windowDays identify the limit window.","properties":{"maxApplications":{"type":"integer","minimum":1},"windowDays":{"type":"integer","minimum":1}},"additionalProperties":true},"ApplicationCreateResult":{"type":"object","required":["id","status","created"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/ApplicationStatus"},"created":{"type":"boolean","description":"False when this is the original resource for an idempotent replay."}}},"Application":{"type":"object","required":["id","jobUrl","mode","status","error","outcomeCode","outcomeDetails","failureCode","requiresAnswers","answerRequest","submittedAnswers"],"description":"Application state. answerRequest and submittedAnswers contain candidate-sensitive prompt/answer data and are returned only when the calling key also has profile:read. requiresAnswers remains available to applications:read-only keys.","properties":{"id":{"type":"string","format":"uuid","example":"529f67cf-7296-40ea-a90a-a1dcc09f1e8d"},"jobUrl":{"type":"string","format":"uri"},"ats":{"type":["string","null"],"example":"workday"},"company":{"type":["string","null"],"example":"Example Labs"},"jobTitle":{"type":["string","null"],"example":"Software Engineer"},"mode":{"type":"string","example":"agent"},"status":{"$ref":"#/components/schemas/ApplicationStatus"},"error":{"type":["string","null"],"deprecated":true,"description":"Legacy-safe alias of outcomeCode. Raw ATS diagnostics are never exposed; new clients should use outcomeCode."},"outcomeCode":{"$ref":"#/components/schemas/ApplicationOutcomeCode","description":"Normalized special outcome for either success or failure. success with already_applied means the employer already had this candidate's application and Apply Guy did not send a duplicate."},"outcomeDetails":{"$ref":"#/components/schemas/ApplicationOutcomeDetails"},"failureCode":{"$ref":"#/components/schemas/ApplicationOutcomeCode","description":"Same normalized value as outcomeCode only when status is failed; otherwise null."},"answerRound":{"type":"integer","minimum":0},"requiresAnswers":{"type":"boolean","description":"True when the application is awaiting an external answer, even when answerRequest is redacted."},"answerRequest":{"anyOf":[{"$ref":"#/components/schemas/AnswerRequest"},{"type":"null"}],"description":"Present only while awaiting_answers and only for keys with profile:read."},"queuedAt":{"type":["string","null"],"format":"date-time"},"startedAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"submittedAnswers":{"type":["object","null"],"additionalProperties":true,"description":"Answer audit data, returned only for keys with profile:read."}}},"ApplicationPreflight":{"type":"object","required":["jobUrl","ats","ready","atsEnabled","modeSupported","emailIntegrationRequired","emailIntegrationConnected","hasResume","hasUploadedResume","missingProfileFields","mode","cost","formDiscovery"],"properties":{"jobUrl":{"type":"string","format":"uri"},"ats":{"type":["string","null"],"example":"greenhouse"},"ready":{"type":"boolean","description":"True only when the ATS, requested mode, profile, resume, and integrations are ready."},"atsEnabled":{"type":"boolean"},"modeSupported":{"type":"boolean","description":"False when this ATS does not support the requested mode. SmartRecruiters is managed-only in v1."},"emailIntegrationRequired":{"type":"boolean"},"emailIntegrationConnected":{"type":"boolean"},"hasResume":{"type":"boolean","description":"True when an uploaded PDF, DOC, or DOCX is available to the application worker."},"hasUploadedResume":{"type":"boolean"},"missingProfileFields":{"type":"array","description":"Exact profile fields that would block application creation for this ATS.","items":{"type":"string"},"example":[]},"mode":{"type":"string","enum":["managed","agent"]},"cost":{"type":"number","example":1},"formDiscovery":{"type":["string","null"],"enum":["during_application",null]}}},"AnswerRequest":{"type":"object","required":["id","fingerprint","prompt","responseSchema","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Send this value back as requestId in the answer envelope."},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"prompt":{"description":"Structured AI SDK prompt payload containing the complete instructions and candidate/job context for this answer round."},"responseSchema":{"type":"object","description":"JSON Schema that the submitted answer must satisfy."},"createdAt":{"type":"string","format":"date-time"}}},"AgentAnswer":{"type":"object","required":["requestId","fingerprint","answer"],"properties":{"requestId":{"type":"string","format":"uuid","example":"905c7655-7582-4556-a13d-bf49fcb63bf8"},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$","example":"b4fc0d55a3f819c70a37f2f8931f29fb848bff0e1f0b7976e5b04e49c015bbd2"},"answer":{"description":"JSON value conforming exactly to answerRequest.responseSchema.","example":{"answers":[{"fieldId":"work_authorization","value":"Yes"}]}}}},"CreditAccount":{"type":"object","required":["balance","balanceMilli","costs","creditsPerDollar"],"properties":{"balance":{"type":"number","example":100},"balanceMilli":{"type":"integer","description":"Internal thousandths of a credit.","example":100000},"costs":{"type":"object","required":["managed","agent","searchPer25","jobDetail"],"properties":{"managed":{"type":"number","const":2,"example":2},"agent":{"type":"number","const":1,"example":1},"searchPer25":{"type":"number","const":0.05,"example":0.05,"description":"Cost for each requested block of up to 25 search results."},"jobDetail":{"type":"number","const":0.01,"example":0.01,"description":"Cost for a job-detail request that returns 200."}}},"creditsPerDollar":{"type":"integer","const":20,"example":20},"minimumPurchaseCents":{"type":"integer","example":500},"maximumPurchaseCents":{"type":"integer","example":100000}}},"CheckoutCreate":{"type":"object","required":["checkoutUrl","sessionId","amountCents","credits"],"properties":{"checkoutUrl":{"type":"string","format":"uri","example":"https://checkout.stripe.com/c/pay/cs_live_a1b2c3"},"sessionId":{"type":"string","example":"cs_live_a1b2c3"},"amountCents":{"type":"integer","example":500},"credits":{"type":"number","example":100}}},"CheckoutStatus":{"type":"object","required":["id","status","paymentStatus"],"properties":{"id":{"type":"string","example":"cs_live_a1b2c3"},"status":{"type":["string","null"],"example":"complete"},"paymentStatus":{"type":"string","example":"paid"}}},"UsageRange":{"type":"string","enum":["24h","7d","30d","90d"],"default":"30d","description":"Rolling reporting window ending at the response endsAt timestamp."},"UsageStatusCounts":{"type":"object","required":["queued","running","awaiting_answers","success","failed","cancelled"],"properties":{"queued":{"type":"integer","minimum":0},"running":{"type":"integer","minimum":0},"awaiting_answers":{"type":"integer","minimum":0},"success":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"cancelled":{"type":"integer","minimum":0}},"additionalProperties":false},"UsageCreditMetrics":{"type":"object","required":["purchased","spent","refunded","netUsed","currentBalance","purchasedMilli","spentMilli","refundedMilli","netUsedMilli","currentBalanceMilli"],"properties":{"purchased":{"type":"number","description":"Credits purchased during the selected range."},"spent":{"type":"number","description":"Gross credits debited for application reservations and job-catalog reads during the selected range."},"refunded":{"type":"number","description":"Application credits refunded during the selected range."},"netUsed":{"type":"number","description":"Spent minus refunded credits during the selected range."},"currentBalance":{"type":"number","description":"Account balance at report generation time."},"purchasedMilli":{"type":"integer","description":"Purchased amount in thousandths of a credit."},"spentMilli":{"type":"integer","description":"Gross application-reservation and job-catalog read spend in thousandths of a credit."},"refundedMilli":{"type":"integer","description":"Refunded amount in thousandths of a credit."},"netUsedMilli":{"type":"integer","description":"Net usage in thousandths of a credit."},"currentBalanceMilli":{"type":"integer","description":"Current balance in thousandths of a credit."}},"additionalProperties":false},"UsageTimeSeriesPoint":{"type":"object","required":["start","applications","success","failed","creditsSpentMilli"],"properties":{"start":{"type":"string","format":"date-time"},"applications":{"type":"integer","minimum":0},"success":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"creditsSpentMilli":{"type":"integer","minimum":0,"description":"Gross application-reservation and job-catalog read spend in this time bucket."}},"additionalProperties":false},"UsageAtsBreakdown":{"type":"object","required":["ats","applications","success","failed","successRate","creditsSpentMilli"],"properties":{"ats":{"type":"string","example":"greenhouse"},"applications":{"type":"integer","minimum":0},"success":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":"number","minimum":0,"maximum":100,"description":"Resolved-outcome success percentage from 0 to 100."},"creditsSpentMilli":{"type":"integer","minimum":0,"description":"Application reservation spend attributed to this ATS. Catalog-read spend is excluded."}},"additionalProperties":false},"UsageModeBreakdown":{"type":"object","required":["mode","applications","success","failed","successRate","creditsSpentMilli"],"properties":{"mode":{"type":"string","enum":["managed","agent"]},"applications":{"type":"integer","minimum":0},"success":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":"number","minimum":0,"maximum":100,"description":"Resolved-outcome success percentage from 0 to 100."},"creditsSpentMilli":{"type":"integer","minimum":0,"description":"Application reservation spend attributed to this execution mode. Catalog-read spend is excluded."}},"additionalProperties":false},"UsageApiKeyBreakdown":{"type":"object","required":["apiKeyId","name","prefix","applications","success","failed","successRate","creditsSpentMilli"],"properties":{"apiKeyId":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string"},"applications":{"type":"integer","minimum":0},"success":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":"number","minimum":0,"maximum":100,"description":"Resolved-outcome success percentage from 0 to 100."},"creditsSpentMilli":{"type":"integer","minimum":0,"description":"Gross application-reservation and job-catalog read spend attributed to this API key."}},"additionalProperties":false},"UsageReport":{"type":"object","required":["range","startsAt","endsAt","bucket","summary","timeSeries","byAts","byMode","byApiKey","failureReasons"],"properties":{"range":{"$ref":"#/components/schemas/UsageRange"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"bucket":{"type":"string","enum":["hour","day"]},"summary":{"type":"object","required":["applications","statuses","successful","successRate","credits","completionMs"],"properties":{"applications":{"type":"integer","minimum":0},"statuses":{"$ref":"#/components/schemas/UsageStatusCounts"},"successful":{"type":"integer","minimum":0},"successRate":{"type":"number","minimum":0,"maximum":100,"description":"Resolved-outcome success percentage: success / (success + failed) × 100, rounded to two decimal places. Excludes queued, running, awaiting-answers, and cancelled applications. Returns 0 when there are no resolved outcomes."},"credits":{"$ref":"#/components/schemas/UsageCreditMetrics"},"completionMs":{"type":"object","required":["p50","p95"],"properties":{"p50":{"type":["number","null"],"minimum":0,"description":"Median completion time in milliseconds, or null with no completed applications."},"p95":{"type":["number","null"],"minimum":0,"description":"95th-percentile completion time in milliseconds, or null with no completed applications."}},"additionalProperties":false}},"additionalProperties":false},"timeSeries":{"type":"array","items":{"$ref":"#/components/schemas/UsageTimeSeriesPoint"}},"byAts":{"type":"array","items":{"$ref":"#/components/schemas/UsageAtsBreakdown"}},"byMode":{"type":"array","items":{"$ref":"#/components/schemas/UsageModeBreakdown"}},"byApiKey":{"type":"array","items":{"$ref":"#/components/schemas/UsageApiKeyBreakdown"}},"failureReasons":{"type":"array","items":{"type":"object","required":["reason","count"],"properties":{"reason":{"type":"string"},"count":{"type":"integer","minimum":0}},"additionalProperties":false}}},"additionalProperties":false},"UsageShareLinkCreate":{"type":"object","properties":{"range":{"$ref":"#/components/schemas/UsageRange"},"expiresInSeconds":{"type":"integer","minimum":3600,"maximum":604800,"default":86400,"description":"Link lifetime from one hour through seven days."}},"additionalProperties":false},"UsageShareLinkCreator":{"oneOf":[{"type":"object","required":["type","apiKeyId","name","prefix"],"properties":{"type":{"type":"string","const":"api_key"},"apiKeyId":{"type":["string","null"],"format":"uuid"},"name":{"type":["string","null"]},"prefix":{"type":["string","null"]}},"additionalProperties":false},{"type":"object","required":["type"],"properties":{"type":{"type":"string","const":"session"}},"additionalProperties":false}]},"UsageShareLink":{"type":"object","required":["id","range","expiresAt","revokedAt","createdAt","lastViewedAt","viewCount","creator"],"description":"Revocable report-link metadata. Listing never exposes the URL or opaque token.","properties":{"id":{"type":"string","format":"uuid"},"range":{"$ref":"#/components/schemas/UsageRange"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"lastViewedAt":{"type":["string","null"],"format":"date-time"},"viewCount":{"type":"integer","minimum":0},"creator":{"$ref":"#/components/schemas/UsageShareLinkCreator"}},"additionalProperties":false},"UsageShareLinkCreated":{"allOf":[{"$ref":"#/components/schemas/UsageShareLink"},{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","readOnly":true,"example":"https://applyguy.ai/developers/usage#rpt_example","description":"One-time report URL. The opaque token is the raw fragment after #, so it is not sent in the navigation request or stored in server access logs. The URL cannot be recovered later."}}}]},"UsageShareLinkExchange":{"type":"object","required":["token"],"properties":{"token":{"type":"string","writeOnly":true,"description":"Opaque value read from the report URL fragment. Never put it in a query string or server log."}},"additionalProperties":false},"WebhookEventType":{"type":"string","enum":["application.queued","application.running","application.awaiting_answers","application.succeeded","application.failed","application.cancelled"]},"WebhookCreate":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://","example":"https://agent.example.com/webhooks/applyguy"},"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/WebhookEventType"},"example":["application.awaiting_answers","application.succeeded","application.failed"]}}},"Webhook":{"type":"object","required":["id","url","events","active"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookCreated":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","readOnly":true,"example":"whsec_••••••••••••••••"}}}],"description":"Webhook metadata plus the one-time signing secret returned only on creation."},"WebhookCreatedResponse":{"type":"object","required":["data","warning"],"properties":{"data":{"$ref":"#/components/schemas/WebhookCreated"},"warning":{"type":"string","example":"Store the signing secret now. It cannot be retrieved again."}}},"WebhookEvent":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"type":"string","format":"uuid","description":"Stable event ID. Use it to deduplicate at-least-once deliveries."},"type":{"$ref":"#/components/schemas/WebhookEventType"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","required":["applicationId","status"],"properties":{"applicationId":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/ApplicationStatus"}}}}}}},"paths":{"/developer/bootstrap":{"post":{"tags":["Setup"],"operationId":"bootstrapDeveloper","summary":"Create an account and first API key","description":"Creates a zero-balance, API-credit-only developer account, an API key, and account access tokens in one call while new registrations are enabled. The API key and refresh token are returned only once. No application can run until credits are purchased.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperBootstrap"},"example":{"email":"agent-builder@example.com","password":"correct-horse-battery-staple","name":"Production agent"}}}},"responses":{"201":{"description":"Account, one-time API key, account tokens, and next setup endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperBootstrapResult"}}}},"400":{"description":"The account or key configuration is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"invalid_input"}}}},"403":{"description":"New account registration is currently paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"signups_disabled"}}}},"409":{"description":"An account already exists for this email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"email_taken"}}}},"413":{"description":"The bootstrap payload exceeds 64 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"payload_too_large"}}}},"429":{"description":"Too many bootstrap attempts from this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"rate_limited"}}}}}}},"/developer/api-keys":{"get":{"tags":["Setup"],"operationId":"listApiKeys","summary":"List API keys","description":"Lists key metadata. Full secrets are never returned after creation.","security":[{"SessionToken":[]}],"responses":{"200":{"description":"API key metadata.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"401":{"description":"The account access token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"unauthenticated"}}}}}},"post":{"tags":["Setup"],"operationId":"createApiKey","summary":"Create an API key","description":"Creates a scoped developer key. Store the returned key immediately because it cannot be retrieved again.","security":[{"SessionToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"},"example":{"name":"CI application agent","scopes":["jobs:read","credits:spend","applications:read","applications:write"]}}}},"responses":{"201":{"description":"One-time API key and metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"400":{"description":"The key configuration is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"invalid_input"}}}},"401":{"description":"The account access token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"unauthenticated"}}}},"409":{"description":"The account already has the maximum 20 active API keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"api_key_limit_reached"}}}},"413":{"description":"The management payload exceeds 64 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"payload_too_large"}}}}}}},"/auth/refresh":{"post":{"tags":["Setup"],"operationId":"refreshAccountSession","summary":"Rotate account access and refresh tokens","description":"Uses the latest refresh token returned by bootstrap or a prior refresh. The old token is revoked; store the replacement atomically. This account token is for API-key and integration management, not /v1 requests.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionRefresh"},"example":{"refreshToken":"the-latest-refresh-token"}}}},"responses":{"200":{"description":"Rotated account tokens.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionRefreshResult"}}}},"400":{"description":"A refresh token is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"invalid_input"}}}},"401":{"description":"The refresh token is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"invalid_refresh"}}}},"409":{"description":"Another request rotated this token first; retry with the token returned by that request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"refresh_raced"}}}},"429":{"description":"Too many refresh attempts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"rate_limited"}}}}}}},"/developer/api-keys/{id}":{"delete":{"tags":["Setup"],"operationId":"revokeApiKey","summary":"Revoke an API key","description":"Immediately revokes a developer API key owned by the account.","security":[{"SessionToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"API key ID.","schema":{"type":"string","format":"uuid","example":"24a9829d-7ec5-4fcc-917c-229006d22b06"}}],"responses":{"204":{"description":"Key revoked."},"400":{"description":"The API key ID must be a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"invalid_input"}}}},"401":{"description":"The account access token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"unauthenticated"}}}},"404":{"description":"The key does not exist or was already revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"not_found"}}}}}}},"/secrets/status":{"get":{"tags":["Integrations"],"operationId":"getEmailIntegrationStatus","summary":"Check Workday email integration readiness","description":"Uses the account accessToken returned by bootstrap, not a developer API key. No email secret is ever returned.","security":[{"SessionToken":[]}],"responses":{"200":{"description":"Email integration readiness and the ATSes that require it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailIntegrationStatus"}}}},"401":{"description":"The account access token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"unauthenticated"}}}}}}},"/secrets/email-integration":{"put":{"tags":["Integrations"],"operationId":"configureEmailIntegration","summary":"Verify and save Gmail IMAP credentials","description":"Uses the account accessToken returned by bootstrap. Apply Guy verifies the Gmail username and 16-character app password over IMAP before encrypting both values. Creating the Gmail app password requires a one-time human Google Account setup; it is required for Workday even though the API call itself is automatable.","security":[{"SessionToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailIntegrationCreate"},"example":{"gmailUser":"candidate@gmail.com","gmailAppPassword":"abcd efgh ijkl mnop"}}}},"responses":{"200":{"description":"Credentials verified and stored.","content":{"application/json":{"schema":{"type":"object","required":["ok","verified"],"properties":{"ok":{"type":"boolean","const":true},"verified":{"type":"boolean","const":true}}}}}},"400":{"description":"The email address or Gmail app-password shape is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"invalid_gmail_app_password"}}}},"401":{"description":"The account access token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"unauthenticated"}}}},"413":{"description":"The integration payload exceeds the management API limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"payload_too_large"}}}},"422":{"description":"Gmail rejected the IMAP credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"invalid_imap_credentials"}}}},"503":{"description":"Gmail credential validation is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagementError"},"example":{"error":"imap_validation_unavailable"}}}}}}},"/v1/jobs":{"get":{"tags":["Jobs"],"operationId":"searchJobs","summary":"Search fresh jobs","description":"Requires both jobs:read and credits:spend. jobs:read alone returns 403 without charging; credits:spend is explicit authorization for this key to incur catalog-read charges and grants no read access by itself. Searches active, non-stale U.S. jobs ordered by recency. A successful 200 costs 0.05 credit per requested block of up to 25 results: limits 1–25 cost 0.05, 26–50 cost 0.10, 51–75 cost 0.15, and 76–100 cost 0.20. Billing uses the requested limit, not the number of matches returned. Invalid requests, authorization failures, rate limits, and 5xx responses are not charged. Use the returned job ID directly when creating an application. Developer API v1 does not expose other country catalogs.","security":[{"ApiKey":[]}],"x-required-scopes":["jobs:read","credits:spend"],"parameters":[{"name":"q","in":"query","description":"Text matched against job title and company.","schema":{"type":"string","maxLength":200,"example":"software engineer"}},{"name":"ats","in":"query","description":"Filter by applicant tracking system.","schema":{"type":"string","maxLength":50,"example":"greenhouse"}},{"name":"country","in":"query","description":"Developer API v1 country. Only US is accepted.","schema":{"type":"string","enum":["US"],"default":"US","example":"US"}},{"name":"remote","in":"query","schema":{"type":"string","enum":["remote","hybrid","onsite"],"example":"remote"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"cursor","in":"query","description":"Numeric offset returned as nextCursor.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0,"example":0}}],"responses":{"200":{"description":"A page of current jobs. With jobs:read and credits:spend, this response is charged and includes decimal cost plus post-charge balance headers, with exact milli-credit equivalents.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"}},"nextCursor":{"type":["string","null"],"example":"25"}}}}},"headers":{"X-ApplyGuy-Credit-Cost":{"description":"Decimal credits charged for this successful request.","schema":{"type":"number","multipleOf":0.001,"example":0.05}},"X-ApplyGuy-Credit-Balance":{"description":"Decimal credit balance after this request was charged.","schema":{"type":"number","multipleOf":0.001,"example":99.95}},"X-ApplyGuy-Credit-Cost-Milli":{"description":"Exact charge in thousandths of a credit. Prefer this header for accounting.","schema":{"type":"integer","minimum":0,"example":50}},"X-ApplyGuy-Credit-Balance-Milli":{"description":"Exact remaining balance in thousandths of a credit. Prefer this header for accounting.","schema":{"type":"integer","minimum":0,"example":99950}}}},"400":{"description":"One or more search filters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"One or more search filters are invalid.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"402":{"description":"The account does not have enough credits for the requested search page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_credits","message":"The account does not have enough credits for the requested search page.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/jobs/{id}":{"get":{"tags":["Jobs"],"operationId":"getJob","summary":"Get a job and cached description","description":"Requires both jobs:read and credits:spend. jobs:read alone returns 403 without charging; credits:spend is explicit authorization for this key to incur catalog-read charges and grants no read access by itself. Returns one active U.S. catalog job, enriched role metadata, and the cached employer-provided description. A successful 200 costs 0.01 credit. Invalid IDs, unavailable or stale jobs, authorization failures, rate limits, and 5xx responses are not charged. Description HTML can be loaded from Apply Guy object storage when the database copy is absent. Stale and non-U.S. jobs intentionally return 404.","security":[{"ApiKey":[]}],"x-required-scopes":["jobs:read","credits:spend"],"parameters":[{"name":"id","in":"path","required":true,"description":"Catalog job ID.","schema":{"type":"string","format":"uuid","example":"951f7024-bbf7-4aa5-98fc-f45625584f9b"}}],"responses":{"200":{"description":"Current job detail. With jobs:read and credits:spend, this response is charged and includes decimal cost plus post-charge balance headers, with exact milli-credit equivalents.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/JobDetail"}}}}},"headers":{"X-ApplyGuy-Credit-Cost":{"description":"Decimal credits charged for this successful request.","schema":{"type":"number","multipleOf":0.001,"example":0.05}},"X-ApplyGuy-Credit-Balance":{"description":"Decimal credit balance after this request was charged.","schema":{"type":"number","multipleOf":0.001,"example":99.95}},"X-ApplyGuy-Credit-Cost-Milli":{"description":"Exact charge in thousandths of a credit. Prefer this header for accounting.","schema":{"type":"integer","minimum":0,"example":50}},"X-ApplyGuy-Credit-Balance-Milli":{"description":"Exact remaining balance in thousandths of a credit. Prefer this header for accounting.","schema":{"type":"integer","minimum":0,"example":99950}}}},"400":{"description":"The job ID must be a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The job ID must be a UUID.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"402":{"description":"The account does not have enough credits to retrieve this job detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_credits","message":"The account does not have enough credits to retrieve this job detail.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"The job is unavailable or stale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"job_not_found","message":"The job is unavailable or stale.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/profile":{"get":{"tags":["Candidate profile"],"operationId":"getCandidateProfile","summary":"Get the candidate profile","description":"Returns the stored candidate context plus resume presence. Requires profile:read.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Candidate profile and resume metadata.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["candidateContext","resumeFilename","hasResume"],"properties":{"candidateContext":{"$ref":"#/components/schemas/CandidateContext"},"resumeFilename":{"type":["string","null"]},"hasResume":{"type":"boolean"}}}}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"put":{"tags":["Candidate profile"],"operationId":"updateCandidateProfile","summary":"Merge candidate profile facts","description":"Merges supplied candidateContext properties into the existing profile. Deterministic fields such as name, contact information, address, and LinkedIn are reused directly during applications.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["candidateContext"],"properties":{"candidateContext":{"$ref":"#/components/schemas/CandidateContext"}}},"example":{"candidateContext":{"firstName":"Jordan","lastName":"Bamber","email":"jordan@example.com","phone":"+1 415 555 0199","location":"San Francisco, CA","linkedin":"https://www.linkedin.com/in/jordan-bamber"}}}}},"responses":{"200":{"description":"Merged candidate profile.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["candidateContext"],"properties":{"candidateContext":{"$ref":"#/components/schemas/CandidateContext"}}}}}}}},"400":{"description":"candidateContext is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"candidateContext is required.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"413":{"description":"The profile payload exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The profile payload exceeds 256 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"422":{"description":"The candidate profile contains invalid values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_profile","message":"The candidate profile contains invalid values.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/profile/resume":{"put":{"tags":["Candidate profile"],"operationId":"uploadResume","summary":"Upload the primary resume","description":"Uploads a PDF, DOC, or DOCX resume up to 5 MB as multipart field file. The resume safely replaces the prior upload and becomes the default document for applications. Uploads are limited to 5 per minute and 20 per hour per account.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Resume uploaded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["filename"],"properties":{"filename":{"type":"string","example":"jordan-resume.pdf"}}}}}}}},"400":{"description":"Upload a multipart field named file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_file","message":"Upload a multipart field named file.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"413":{"description":"The multipart payload or resume exceeds the 5 MB file limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"file_too_large","message":"The multipart payload or resume exceeds the 5 MB file limit.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"422":{"description":"The file type or size is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unsupported_file_type","message":"The file type or size is unsupported.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"503":{"description":"Resume storage is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"storage_unavailable","message":"Resume storage is temporarily unavailable.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/credits":{"get":{"tags":["Credits"],"operationId":"getCredits","summary":"Get balance, pricing, and purchase bounds","description":"Returns the live balance and pricing. There are 20 credits per dollar. Search costs 0.05 credit per requested block of up to 25 results, a job-detail 200 costs 0.01 credit, managed applications cost 2 credits, and bring-your-own-agent applications cost 1 credit.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Credit account.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CreditAccount"}}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/credits/checkout":{"post":{"tags":["Credits"],"operationId":"createCreditCheckout","summary":"Create hosted checkout for a dollar amount","description":"Creates a Stripe-hosted checkout session for any whole-cent USD amount within the bounds returned by GET /v1/credits. Stripe requires human payment approval. Workday separately requires a one-time human Google Account step to create a Gmail app password.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amountCents"],"properties":{"amountCents":{"type":"integer","example":500,"description":"$5.00, yielding 100 credits at the current rate."}}},"example":{"amountCents":500}}}},"responses":{"201":{"description":"Hosted checkout URL and expected credit grant.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CheckoutCreate"}}}}}},"400":{"description":"The amount is outside the advertised purchase bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_amount","message":"The amount is outside the advertised purchase bounds.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"The developer credit account was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"The developer credit account was not found.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"413":{"description":"The JSON payload exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The JSON payload exceeds 256 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"503":{"description":"Billing is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"billing_unavailable","message":"Billing is temporarily unavailable.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/credits/checkout/{id}":{"get":{"tags":["Credits"],"operationId":"getCreditCheckout","summary":"Poll checkout and reconcile paid credits","description":"Returns Stripe checkout state. If payment completed before the webhook arrived, this request safely reconciles the credit grant.","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Stripe Checkout Session ID.","schema":{"type":"string","example":"cs_live_a1b2c3"}}],"responses":{"200":{"description":"Checkout state. A paid response means the credit grant has been reconciled.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CheckoutStatus"}}}}}},"400":{"description":"The checkout session ID is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The checkout session ID is invalid.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"The checkout session is not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"The checkout session is not owned by this account.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"503":{"description":"Billing is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"billing_unavailable","message":"Billing is temporarily unavailable.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/usage":{"get":{"tags":["Usage"],"operationId":"getUsageReport","summary":"Get application and credit usage analytics","description":"Returns outcome counts, success rate, completion-time percentiles, credit economics, time-series buckets, ATS/mode/API-key breakdowns, and normalized failure reasons. Requires usage:read. successRate is a 0–100 percentage computed as success / (success + failed) × 100, excluding in-progress and cancelled applications; it is 0 when no outcomes are resolved. Reports contain operational aggregates, not candidate PII.","security":[{"ApiKey":[]}],"parameters":[{"name":"range","in":"query","description":"Rolling reporting range. Defaults to 30d.","schema":{"$ref":"#/components/schemas/UsageRange"}}],"responses":{"200":{"description":"Usage analytics for the selected range.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/UsageReport"}}}}}},"400":{"description":"The usage range is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The usage range is invalid.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/usage/share-links":{"get":{"tags":["Usage"],"operationId":"listUsageShareLinks","summary":"List usage report links","description":"Lists revocable report-link metadata for this account. Requires usage:share. The one-time URL and its opaque token are never returned by list operations. Reports contain operational aggregates, not candidate PII.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Usage share-link metadata without URLs or tokens.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageShareLink"}}}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"post":{"tags":["Usage"],"operationId":"createUsageShareLink","summary":"Create a read-only usage report link","description":"Creates a revocable report link containing operational aggregates but no candidate PII. Requires usage:share. The response is the only time the URL is available. Its opaque token appears only in the URL fragment after #, so browsers do not include it in the initial HTTP navigation request. Store or send the full URL immediately. An account can have at most 20 active links.","security":[{"ApiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageShareLinkCreate"},"example":{"range":"30d","expiresInSeconds":86400}}}},"responses":{"201":{"description":"Share-link metadata plus its one-time fragment-token URL.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/UsageShareLinkCreated"}}}}}},"400":{"description":"The range or expiration is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The range or expiration is invalid.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"409":{"description":"The account already has the maximum 20 active report links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"share_link_limit_reached","message":"The account already has the maximum 20 active report links.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"413":{"description":"The share-link payload exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The share-link payload exceeds 256 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/usage/share-links/exchange":{"post":{"tags":["Usage"],"operationId":"exchangeUsageShareLink","summary":"Exchange a report token for read-only usage analytics","description":"Public exchange used by a shared report page. Read the token from the URL fragment, remove the fragment from browser history, then send the token only in this JSON body. Expired, revoked, unknown, and malformed tokens all receive the same generic 404 response.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageShareLinkExchange"},"example":{"token":"rpt_opaque_fragment_value"}}}},"responses":{"200":{"description":"The immutable range selected when the link was created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/UsageReport"}}}}}},"400":{"description":"A token is required in the JSON body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"A token is required in the JSON body.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"404":{"description":"The report link is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_share_link","message":"The report link is unavailable.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"413":{"description":"The exchange payload exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The exchange payload exceeds 256 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"Too many exchange attempts. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many exchange attempts. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/usage/share-links/{id}":{"delete":{"tags":["Usage"],"operationId":"revokeUsageShareLink","summary":"Revoke a usage report link","description":"Immediately revokes a report link owned by the account. Requires usage:share. Later exchanges return the same generic 404 used for expired or unknown links.","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Usage share-link ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Report link revoked."},"400":{"description":"The share-link ID must be a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The share-link ID must be a UUID.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"The report link was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"The report link was not found.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/applications/preflight":{"post":{"tags":["Applications"],"operationId":"preflightApplication","summary":"Check readiness before spending credits","description":"Checks ATS availability, required profile facts, resume presence, inbox requirements, requested mode, and cost. A catalog jobId is also checked for current U.S. catalog eligibility and freshness. A caller-supplied raw jobUrl is validated for supported ATS ownership and URL shape, but its live availability and U.S. suitability are not known until the application runs. Preflight is free and no credits are reserved.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationCreate"},"example":{"jobId":"951f7024-bbf7-4aa5-98fc-f45625584f9b","mode":"agent"}}}},"responses":{"200":{"description":"Readiness details and exact application cost.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ApplicationPreflight"}}},"example":{"data":{"jobUrl":"https://boards.greenhouse.io/example/jobs/123456","ats":"greenhouse","ready":true,"atsEnabled":true,"modeSupported":true,"emailIntegrationRequired":false,"emailIntegrationConnected":true,"hasResume":true,"hasUploadedResume":true,"missingProfileFields":[],"mode":"agent","cost":1,"formDiscovery":"during_application"}}}}},"400":{"description":"Provide exactly one jobId or jobUrl.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Provide exactly one jobId or jobUrl.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"The catalog job is unavailable or stale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"job_not_found","message":"The catalog job is unavailable or stale.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"413":{"description":"The JSON payload exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The JSON payload exceeds 256 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"422":{"description":"The ATS or raw employer URL is unsupported or unsafe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unsupported_ats","message":"The ATS or raw employer URL is unsupported or unsafe.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/applications":{"get":{"tags":["Applications"],"operationId":"listApplications","summary":"List developer applications","description":"Returns up to the 100 most recently queued developer applications for the account. applications:read exposes requiresAnswers, but answerRequest and submittedAnswers are redacted unless the key also has profile:read.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Recent developer applications.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}}}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"post":{"tags":["Applications"],"operationId":"createApplication","summary":"Reserve credits and start an application","description":"Queues a job application and atomically reserves its credits. Reusing the same Idempotency-Key with the same API key and equivalent request returns the original application instead of charging twice; reusing it for a different job or mode returns idempotency_conflict. A user can have only one application in progress per canonical employer target. A prior success returns already_applied, and two failed runs for the same target in a rolling 24-hour window return application_retry_limit_reached until the Retry-After delay expires. Rotating API keys, changing idempotency keys, or adding tracking query parameters does not create a new target identity.","security":[{"ApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique operation key, at most 200 characters.","schema":{"type":"string","maxLength":200,"example":"apply-job-951f7024-v1"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationCreate"},"example":{"jobId":"951f7024-bbf7-4aa5-98fc-f45625584f9b","mode":"managed"}}}},"responses":{"200":{"description":"The equivalent idempotent request already exists.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ApplicationCreateResult"}}}}}},"201":{"description":"Application created and queued.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ApplicationCreateResult"}}}}}},"400":{"description":"The body or Idempotency-Key is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"idempotency_key_required","message":"The body or Idempotency-Key is invalid.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"402":{"description":"The account does not have enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_credits","message":"The account does not have enough credits.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"The catalog job is unavailable or stale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"job_not_found","message":"The catalog job is unavailable or stale.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"409":{"description":"The ATS is disabled, the mode is unsupported, a required inbox is disconnected, an equivalent target is already active/successful, the target reached two failed attempts in 24 hours, or the Idempotency-Key was reused for a different request. Codes: ats_disabled, agent_mode_unsupported, email_integration_required, application_already_in_progress, already_applied, application_retry_limit_reached, idempotency_conflict. Retry-limit responses include failedAttempts, limit, windowHours, retryAt, and retryAfterSeconds details and a Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"application_retry_limit_reached","message":"The ATS is disabled, the mode is unsupported, a required inbox is disconnected, an equivalent target is already active/successful, the target reached two failed attempts in 24 hours, or the Idempotency-Key was reused for a different request. Codes: ats_disabled, agent_mode_unsupported, email_integration_required, application_already_in_progress, already_applied, application_retry_limit_reached, idempotency_conflict. Retry-limit responses include failedAttempts, limit, windowHours, retryAt, and retryAfterSeconds details and a Retry-After header.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"413":{"description":"The JSON payload exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The JSON payload exceeds 256 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"422":{"description":"Required profile fields are incomplete, or the ATS/raw employer URL is unsupported or unsafe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"profile_incomplete","message":"Required profile fields are incomplete, or the ATS/raw employer URL is unsupported or unsafe.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/applications/{id}":{"get":{"tags":["Applications"],"operationId":"getApplication","summary":"Get application state","description":"Returns the latest state and stable failure reason. requiresAnswers is always visible; candidate-sensitive answerRequest and submittedAnswers require profile:read in addition to applications:read.","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Application ID.","schema":{"type":"string","format":"uuid","example":"529f67cf-7296-40ea-a90a-a1dcc09f1e8d"}}],"responses":{"200":{"description":"Application state.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Application"}}}}}},"400":{"description":"The application ID must be a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The application ID must be a UUID.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Application not found.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/applications/{id}/answer-request":{"get":{"tags":["Agent answers"],"operationId":"getAnswerRequest","summary":"Get a pending agent prompt and JSON Schema","description":"When an agent-mode application enters awaiting_answers, fetch this request and have your own model return JSON matching responseSchema. This endpoint requires both applications:read and profile:read because the prompt contains candidate data.","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Application ID.","schema":{"type":"string","format":"uuid","example":"529f67cf-7296-40ea-a90a-a1dcc09f1e8d"}}],"responses":{"200":{"description":"Pending answer request.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AnswerRequest"}}}}}},"400":{"description":"The application ID must be a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The application ID must be a UUID.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Application not found.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"409":{"description":"The application is not awaiting answers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_awaiting_answers","message":"The application is not awaiting answers.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/applications/{id}/answers":{"post":{"tags":["Agent answers"],"operationId":"submitAgentAnswers","summary":"Validate an agent answer and resume","description":"Validates answer against the exact responseSchema, rejects stale fingerprints, and resumes the application. A later form step may create another answer round.","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Application ID.","schema":{"type":"string","format":"uuid","example":"529f67cf-7296-40ea-a90a-a1dcc09f1e8d"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAnswer"},"example":{"requestId":"905c7655-7582-4556-a13d-bf49fcb63bf8","fingerprint":"b4fc0d55a3f819c70a37f2f8931f29fb848bff0e1f0b7976e5b04e49c015bbd2","answer":{"answers":[{"fieldId":"work_authorization","value":"Yes"}]}}}}},"responses":{"202":{"description":"Answer accepted and application re-queued.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"queued"}}}}}}}},"400":{"description":"The answer envelope is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The answer envelope is invalid.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"409":{"description":"The request is stale or no longer pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"answer_request_conflict","message":"The request is stale or no longer pending.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"413":{"description":"The external answer envelope exceeds 64 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The external answer envelope exceeds 64 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"422":{"description":"The answer does not match responseSchema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"answer_schema_invalid","message":"The answer does not match responseSchema.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/applications/{id}/cancel":{"post":{"tags":["Applications"],"operationId":"cancelApplication","summary":"Cancel before submission","description":"Cancels a queued or awaiting-answers application. Reserved developer credits are refunded idempotently.","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Application ID.","schema":{"type":"string","format":"uuid","example":"529f67cf-7296-40ea-a90a-a1dcc09f1e8d"}}],"responses":{"200":{"description":"Application cancelled and credits refunded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The application ID must be a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The application ID must be a UUID.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"Application not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Application not found.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"409":{"description":"The application can no longer be cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_cancellable","message":"The application can no longer be cancelled.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"operationId":"listWebhooks","summary":"List webhooks","description":"Lists webhook endpoints and subscribed events. Signing secrets are never returned after creation.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Registered webhooks.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"post":{"tags":["Webhooks"],"operationId":"createWebhook","summary":"Register a signed HTTPS webhook","description":"Registers a public HTTPS endpoint. The HMAC-SHA256 signing secret is returned once. If events is omitted, all application events are subscribed. An account can register at most 10 endpoints and cannot register the same URL twice.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"},"example":{"url":"https://agent.example.com/webhooks/applyguy","events":["application.awaiting_answers","application.succeeded","application.failed"]}}}},"responses":{"201":{"description":"Webhook and one-time signing secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreatedResponse"}}}},"400":{"description":"The URL or event list is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The URL or event list is invalid.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"409":{"description":"The URL is already registered or the account has reached 10 webhooks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"webhook_url_exists","message":"The URL is already registered or the account has reached 10 webhooks.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"413":{"description":"The JSON payload exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The JSON payload exceeds 256 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"422":{"description":"The URL is not a public HTTPS endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unsafe_webhook_url","message":"The URL is not a public HTTPS endpoint.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}},"/v1/webhooks/{id}":{"patch":{"tags":["Webhooks"],"operationId":"updateWebhook","summary":"Update a webhook","description":"Changes the URL, event subscriptions, or active state of an existing webhook.","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID.","schema":{"type":"string","format":"uuid","example":"ec41686d-d579-48c6-9b92-b47cfa086f93"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"active":{"type":"boolean"}}},"example":{"active":false}}}},"responses":{"200":{"description":"Updated webhook.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"description":"The webhook update is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The webhook update is invalid.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Webhook not found.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"413":{"description":"The JSON payload exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The JSON payload exceeds 256 KB.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"422":{"description":"The URL is not a public HTTPS endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unsafe_webhook_url","message":"The URL is not a public HTTPS endpoint.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"delete":{"tags":["Webhooks"],"operationId":"deleteWebhook","summary":"Delete a webhook","description":"Permanently removes a webhook endpoint owned by the account.","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID.","schema":{"type":"string","format":"uuid","example":"ec41686d-d579-48c6-9b92-b47cfa086f93"}}],"responses":{"204":{"description":"Webhook deleted."},"400":{"description":"The webhook ID must be a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The webhook ID must be a UUID.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"401":{"description":"Authentication failed. Code is unauthenticated when the Bearer token is missing and invalid_api_key when the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingBearer":{"value":{"error":{"code":"unauthenticated","message":"Provide an Apply Guy API key as a Bearer token.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"invalidKey":{"value":{"error":{"code":"invalid_api_key","message":"The API key is invalid, expired, or revoked.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"403":{"description":"The key lacks a required scope (insufficient_scope), or the developer account is frozen for manual review after a payment dispute (account_frozen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":{"code":"insufficient_scope","message":"Missing API scope: applications:write.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"missingCatalogSpendScope":{"summary":"A catalog key can read job resources but is not allowed to spend credits","value":{"error":{"code":"insufficient_scope","message":"Missing API scope: credits:spend.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}},"frozenAccount":{"value":{"error":{"code":"account_frozen","message":"Developer API access is frozen. Contact support to restore access.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Webhook not found.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}},"429":{"description":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"The developer API rate limit was exceeded. Retry after the number of seconds in Retry-After.","requestId":"req_01JYZ6K2R8YV4R8G9AWM7M6XBP"}}}}}}}}},"webhooks":{"applicationStatus":{"post":{"tags":["Webhooks"],"operationId":"receiveApplicationWebhook","summary":"Receive an application status event","description":"Apply Guy delivers events at least once. Return any 2xx within 10 seconds to acknowledge. Network errors and non-2xx responses are retried up to 12 total attempts with exponential backoff beginning at 30 seconds and capped at one hour. Deduplicate with the stable event ID in the body or X-ApplyGuy-Delivery. Verify X-ApplyGuy-Signature before parsing or acting: compute the lowercase hex HMAC-SHA256 of `<X-ApplyGuy-Timestamp>.<raw request body>` using the one-time webhook secret, then compare it to the value after `v1=` using a timing-safe comparison.","parameters":[{"name":"X-ApplyGuy-Event","in":"header","required":true,"description":"Event type.","schema":{"$ref":"#/components/schemas/WebhookEventType"}},{"name":"X-ApplyGuy-Delivery","in":"header","required":true,"description":"Stable event/delivery identifier.","schema":{"type":"string","format":"uuid"}},{"name":"X-ApplyGuy-Timestamp","in":"header","required":true,"description":"Unix timestamp in seconds used in the signature input.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"X-ApplyGuy-Signature","in":"header","required":true,"description":"Versioned HMAC-SHA256 signature of timestamp dot raw body.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"f0279a18-4c2d-4973-8f26-37d60e88ada3","type":"application.awaiting_answers","createdAt":"2026-08-23T18:04:11.000Z","data":{"applicationId":"529f67cf-7296-40ea-a90a-a1dcc09f1e8d","status":"awaiting_answers"}}}}},"responses":{"2XX":{"description":"Event acknowledged; no retry is scheduled."}}}}}}