{"openapi":"3.0.0","info":{"title":"CazVid Job Builder Public API","version":"1.0.0","description":"Generate and create CazVid job posts programmatically. See https://cazvid.com/api/job-builder/v1 for guides and examples."},"servers":[{"url":"https://aio-backend-prod.cazvid.app"}],"paths":{"/api/v3.0/job-builder/public/generate":{"post":{"operationId":"publicJobBuilderGenerateDetails","summary":"","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicJobBuilderGenerateDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicJobBuilderGeneratedJobDto"}}}}},"tags":["Job Builder API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/job-builder/public/jobs":{"post":{"operationId":"publicJobBuilderCreateDraftJob","summary":"","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicJobBuilderCreateJobDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicJobBuilderCreateJobResponseDto"}}}}},"tags":["Job Builder API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/job-builder/public/usage":{"get":{"operationId":"publicJobBuilderUsage","summary":"Current daily quota usage for the calling organization.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key>. Does not consume daily quota. Throttled to 60 requests per minute per API key.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicJobBuilderUsageDto"}}}}},"tags":["Job Builder API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}}},"components":{"schemas":{"PublicJobBuilderGenerateDto":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"Natural-language job request, e.g. 'remote support agent in Mexico'."},"language":{"type":"string","enum":["en","es","nl","pt"]},"workspaceId":{"type":"string"},"organizationId":{"type":"string"},"includeDescription":{"type":"boolean","default":false,"description":"When true, also generates the editable job description used by the app posting flow."}},"required":["prompt","language"]},"PublicJobBuilderGeneratedJobDto":{"type":"object","properties":{"title":{"type":"string"},"language":{"type":"string","enum":["en","es","nl","pt"]},"workMode":{"$ref":"#/components/schemas/PublicJobBuilderWorkModeDto"},"salary":{"$ref":"#/components/schemas/PublicJobBuilderSalaryDto"},"primaryEmploymentType":{"type":"string","nullable":true},"employmentTypes":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/PublicJobBuilderCategoryDto"}},"education":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"string"}},"locationSource":{"type":"string","enum":["generated","account_fallback","unresolved"],"description":"Where the location came from. 'generated': derived from the prompt. 'account_fallback': the prompt named no recognizable city, so the API key owner's account location was used (change it in the app if the job is elsewhere). 'unresolved': no location could be determined and the account has none either; set it in the app before publishing."},"description":{"type":"string","nullable":true}},"required":["title","language","workMode","salary","employmentTypes","categories","education","skills","locationSource"]},"PublicJobBuilderCreateJobDto":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"Natural-language job request, e.g. 'remote support agent in Mexico'."},"language":{"type":"string","enum":["en","es","nl","pt"]},"workspaceId":{"type":"string"},"organizationId":{"type":"string"},"includeDescription":{"type":"boolean","default":false,"description":"When true, also generates the editable job description used by the app posting flow."},"publishMode":{"type":"string","enum":["draft","publish"],"default":"draft","description":"draft creates an editable app draft. publish creates a standard/free post and sends it through the normal approval pipeline."},"screeningQuestions":{"type":"boolean","default":false,"description":"Screening questions are not generated by the public API v1 flow."}},"required":["prompt","language"]},"PublicJobBuilderCreateJobResponseDto":{"type":"object","properties":{"postId":{"type":"string"},"listId":{"type":"string","nullable":true},"publishMode":{"type":"string","enum":["draft","publish"]},"status":{"type":"string"},"completePost":{"type":"boolean"},"jobBuilderProgress":{"type":"number","nullable":true},"job":{"$ref":"#/components/schemas/PublicJobBuilderGeneratedJobDto"}},"required":["postId","publishMode","status","completePost","job"]},"PublicJobBuilderUsageDto":{"type":"object","properties":{"dailyQuota":{"type":"number","description":"Maximum successful public-API calls allowed per organization per UTC day.","example":10},"used":{"type":"number","description":"Quota-consuming API calls made with this organization's API keys today (UTC).","example":3},"remaining":{"type":"number","description":"Calls still available today: max(0, dailyQuota - used).","example":7},"resetsAt":{"type":"string","description":"ISO-8601 timestamp of the next UTC midnight, when used resets to 0.","example":"2026-07-07T00:00:00.000Z"},"period":{"type":"string","description":"Quota window. Always utc_day in v1.","enum":["utc_day"],"example":"utc_day"}},"required":["dailyQuota","used","remaining","resetsAt","period"]},"PublicJobBuilderWorkModeDto":{"type":"object","properties":{"type":{"type":"string","enum":["remote","onsite","hybrid"]},"scope":{"type":"string","enum":["country","worldwide"],"nullable":true},"countryCode":{"type":"string","nullable":true},"countryName":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"displayName":{"type":"string","nullable":true},"geoNameId":{"type":"object","nullable":true},"coordinates":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/PublicJobBuilderCoordinatesDto"}]}},"required":["type"]},"PublicJobBuilderSalaryDto":{"type":"object","properties":{"low":{"type":"number","nullable":true},"recommended":{"type":"number","nullable":true},"high":{"type":"number","nullable":true},"period":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"currencySymbol":{"type":"string","nullable":true},"negotiable":{"type":"boolean"},"additionalCompensation":{"type":"array","items":{"type":"string"}}},"required":["negotiable","additionalCompensation"]},"PublicJobBuilderCategoryDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"primary":{"type":"boolean"}},"required":["id","name","primary"]},"PublicJobBuilderCoordinatesDto":{"type":"object","properties":{"longitude":{"type":"number"},"latitude":{"type":"number"}},"required":["longitude","latitude"]}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"bearer":{"type":"http","scheme":"bearer"}}}}