{"openapi":"3.1.0","info":{"title":"UpHunt API","version":"2.0.0","summary":"Programmatic auto-apply for Upwork jobs.","description":"The UpHunt API lets you apply to any Upwork job programmatically by passing a job URL or ciphertext. No job feeds required. Use this API to build automated freelance-application pipelines, integrate with webhook events, and generate AI cover letters.","contact":{"name":"UpHunt Support","url":"https://uphunt.io/docs"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://uphunt.io","description":"Production"}],"externalDocs":{"description":"Human-readable API reference","url":"https://uphunt.io/docs"},"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Applications","description":"Submit and track Upwork auto-apply jobs."},{"name":"Proposals","description":"Generate AI-written cover letters."},{"name":"Freelancers","description":"List freelancer profiles available for applications."},{"name":"Legacy","description":"Original v1 endpoints kept for backward compatibility."}],"paths":{"/api/auto-apply-v2/apply":{"post":{"tags":["Applications"],"operationId":"applyToJob","summary":"Submit a proposal to an Upwork job","description":"Queues a proposal submission for an Upwork job. One credit is deducted on successful submission. Accepts a job URL, ciphertext, or a processed job UUID.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyRequest"}}}},"responses":{"200":{"description":"Job queued for auto-apply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient auto-apply credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCreditsError"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/auto-apply-v2/status":{"get":{"tags":["Applications"],"operationId":"getApplicationStatus","summary":"Check application status","description":"Poll the current status of a submitted application. Provide either queueId or jobId.","parameters":[{"name":"queueId","in":"query","schema":{"type":"string"},"description":"Queue ID returned from the apply endpoint."},{"name":"jobId","in":"query","schema":{"type":"string"},"description":"Upwork ciphertext (e.g. ~01abc...) or processed job UUID."}],"responses":{"200":{"description":"Current application state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/auto-apply-v2/applied-jobs":{"get":{"tags":["Applications"],"operationId":"listAppliedJobs","summary":"List applied jobs","description":"Paginated list of jobs you have applied to or attempted to apply to.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200,"minimum":1}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}},{"name":"status","in":"query","description":"Filter by applicationStatus. Returns all statuses if omitted.","schema":{"$ref":"#/components/schemas/ApplicationStatus"}}],"responses":{"200":{"description":"List of applied jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppliedJobsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/auto-apply-v2/generate-proposal":{"post":{"tags":["Proposals"],"operationId":"generateProposal","summary":"Generate an AI cover letter","description":"Returns an AI-written cover letter for a job. Pass jobId to look up a scraped job, or jobTitle + jobDescription to skip the lookup.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateProposalRequest"}}}},"responses":{"200":{"description":"Generated proposal text","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateProposalResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/auto-apply/external/freelancers":{"get":{"tags":["Freelancers"],"operationId":"listFreelancers","summary":"List agency freelancers and profiles","description":"Lists freelancers connected to your agency account along with their default and specialization profiles. Use the returned profileId when submitting proposals.","responses":{"200":{"description":"Freelancers and their profiles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreelancersResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/auto-apply/external":{"post":{"tags":["Legacy"],"operationId":"applyLegacy","summary":"Legacy auto-apply endpoint (v1)","description":"Original auto-apply API. Prefer /api/auto-apply-v2/apply for new integrations. Accepts processed job UUIDs and ciphertexts from feed webhooks.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyApplyRequest"}}}},"responses":{"200":{"description":"Legacy apply response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"deprecated":true}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Obtain from Dashboard → Auto-Apply → API & Webhooks."}},"responses":{"BadRequest":{"description":"Invalid request body or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Already applied or currently processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."}}},"InsufficientCreditsError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"Insufficient auto-apply credits"},"creditsRemaining":{"type":"integer","example":0},"needsCredits":{"type":"boolean","example":true}}},"Timeline":{"type":"string","enum":["Less than 1 month","1 to 3 months","3 to 6 months","More than 6 months"]},"ReasoningEffort":{"type":"string","enum":["low","medium","high"]},"ApplicationStatus":{"type":"string","enum":["processing","applied","failed","not_available","not_eligible","not_enough_connects","logged_out"]},"Proposal":{"type":"object","description":"Bid details. Hourly rate applies to hourly jobs; fixedBid applies to fixed-price jobs.","properties":{"hourlyRate":{"type":"number","description":"USD hourly rate bid.","example":65},"fixedBid":{"type":"number","description":"USD fixed-price bid.","example":1000},"timeline":{"$ref":"#/components/schemas/Timeline"},"boostBids":{"type":"integer","description":"Extra Connects to boost the proposal's visibility.","example":10}}},"ApplyRequest":{"type":"object","required":["jobId","coverLetter"],"properties":{"jobId":{"type":"string","description":"Upwork job identifier. Accepts ciphertext (~01abc...), full URL, or processed job UUID.","example":"~01abc123def456"},"coverLetter":{"type":"string","description":"Proposal/cover letter text."},"profileId":{"type":"string","description":"Freelancer profileId from /api/auto-apply/external/freelancers. Uses primary profile if omitted."},"proposal":{"$ref":"#/components/schemas/Proposal"},"autoFillOtherQuestions":{"type":"boolean","default":false,"description":"Use AI to answer additional screening questions on the application form."}}},"ApplyResponse":{"type":"object","required":["success","queueId"],"properties":{"success":{"type":"boolean","example":true},"queueId":{"type":"string","example":"queue_abc123"},"creditsRemaining":{"type":"integer","example":42},"message":{"type":"string"}}},"StatusResponse":{"type":"object","properties":{"jobId":{"type":"string","nullable":true},"processedJobId":{"type":"string","nullable":true},"applicationStatus":{"allOf":[{"$ref":"#/components/schemas/ApplicationStatus"}],"nullable":true},"applicationStatusMessage":{"type":"string","nullable":true},"queueId":{"type":"string","nullable":true},"appliedAt":{"type":"integer","format":"int64","nullable":true,"description":"Unix ms timestamp."},"processedAt":{"type":"integer","format":"int64","nullable":true},"errorMessage":{"type":"string","nullable":true}}},"AppliedJob":{"type":"object","properties":{"jobId":{"type":"string","nullable":true,"description":"Ciphertext or processed job UUID."},"processedJobId":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"url":{"type":"string","nullable":true,"format":"uri"},"platform":{"type":"string","enum":["upwork","linkedin"],"example":"upwork"},"applicationStatus":{"allOf":[{"$ref":"#/components/schemas/ApplicationStatus"}],"nullable":true},"applicationStatusMessage":{"type":"string","nullable":true},"matchingScore":{"type":"number","nullable":true},"queueId":{"type":"string","nullable":true},"appliedAt":{"type":"integer","format":"int64","nullable":true},"processedAt":{"type":"integer","format":"int64","nullable":true},"errorMessage":{"type":"string","nullable":true},"coverLetter":{"type":"string","nullable":true},"createdAt":{"type":"integer","format":"int64","nullable":true}}},"AppliedJobsResponse":{"type":"object","required":["jobs","total","limit","offset"],"properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/AppliedJob"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"GenerateProposalRequest":{"type":"object","description":"Pass jobId to look up a scraped job, or jobTitle + jobDescription to skip the lookup.","properties":{"jobId":{"type":"string","description":"Ciphertext, full URL, or processed job UUID."},"jobTitle":{"type":"string"},"jobDescription":{"type":"string"},"feedId":{"type":"string","description":"Job listener ID whose custom prompt should be used."},"reasoningEffort":{"$ref":"#/components/schemas/ReasoningEffort"}}},"GenerateProposalResponse":{"type":"object","required":["success","proposal"],"properties":{"success":{"type":"boolean"},"proposal":{"type":"string"}}},"FreelancerProfile":{"type":"object","properties":{"type":{"type":"string","enum":["default","specialization"]},"name":{"type":"string"},"hourlyRate":{"type":"number","nullable":true},"currency":{"type":"string","example":"USD"},"profileId":{"type":"string","description":"Value to pass as profileId when calling the apply endpoint. Ciphertext for default profiles; service UID for specializations."}}},"Freelancer":{"type":"object","properties":{"id":{"type":"string","description":"Freelancer's Upwork ciphertext."},"name":{"type":"string"},"avatarUrl":{"type":"string","nullable":true,"format":"uri"},"baseHourlyRate":{"type":"number","nullable":true},"profiles":{"type":"array","items":{"$ref":"#/components/schemas/FreelancerProfile"}}}},"FreelancersResponse":{"type":"object","required":["freelancers"],"properties":{"freelancers":{"type":"array","items":{"$ref":"#/components/schemas/Freelancer"}}}},"LegacyApplyRequest":{"type":"object","required":["jobId","coverLetter"],"properties":{"jobId":{"type":"string","description":"Ciphertext or processed job UUID."},"coverLetter":{"type":"string"},"applicationOptions":{"type":"object","properties":{"hourlyRate":{"type":"number"},"fixedBid":{"type":"number"},"timeline":{"$ref":"#/components/schemas/Timeline"},"boostBids":{"type":"integer"}}},"autoFillOtherQuestions":{"type":"boolean"}}}}}}