{"openapi":"3.1.0","info":{"title":"HireFlock Developer API","version":"1.0.0","description":"Public, company-scoped API for programmatic access to your HireFlock data.\n\nAuthenticate with an API key created from the HireFlock dashboard (**API Keys** section). Send it as a Bearer token:\n\n```\nAuthorization: Bearer hf_live_xxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nAll responses use a consistent envelope: `{ \"success\": true, \"data\": { ... } }` on success, or `{ \"success\": false, \"error\": { \"message\", \"code\" } }` on failure.","contact":{"name":"HireFlock","url":"https://hireflock.ai"}},"servers":[{"url":"https://api.hireflock.ai","description":"Production"}],"tags":[{"name":"Jobs","description":"Job postings for the authenticated company."},{"name":"System","description":"Service health checks (no authentication)."}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/v1/jobs":{"get":{"tags":["Jobs"],"summary":"List job postings","description":"Returns the authenticated company's job postings, newest first. Results are scoped to your company.","operationId":"listJobs","parameters":[{"name":"page","in":"query","description":"1-based page number.","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Items per page (max 100).","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"acceptingApplications","in":"query","description":"Filter by whether the posting is currently accepting applications.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"A paginated list of jobs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/jobs/{id}":{"get":{"tags":["Jobs"],"summary":"Get a job posting","description":"Fetch a single job posting by its id. Returns 404 if it does not exist or belongs to another company.","operationId":"getJob","parameters":[{"name":"id","in":"path","required":true,"description":"Job posting id (JobProfileExperience id).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The job posting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/health":{"get":{"tags":["System"],"summary":"Liveness check","operationId":"health","security":[],"responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"developer-api"}}}}}}}}}}},"/health/ready":{"get":{"tags":["System"],"summary":"Readiness check (pings the database)","operationId":"ready","security":[],"responses":{"200":{"description":"Service and database are ready."},"503":{"description":"Database not reachable."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Provide your API key as `Authorization: Bearer hf_live_...`."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternatively, provide your API key in the `x-api-key` header."}},"schemas":{"Job":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Job posting id."},"jobProfileId":{"type":"string","format":"uuid"},"title":{"type":"string","example":"Laravel Developer"},"category":{"type":"string","example":"Software & Development"},"yearsOfExperience":{"type":["integer","null"],"example":3},"language":{"type":["string","null"],"example":"English"},"workType":{"type":["string","null"],"example":"ON_SITE"},"qualities":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"string"},"example":["Laravel","SQL"]},"acceptingApplications":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":1},"totalPages":{"type":"integer","example":1}}},"JobListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}},"JobResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"value":{"success":false,"error":{"message":"Missing API key.","code":"MISSING_API_KEY"}}},"invalid":{"value":{"success":false,"error":{"message":"Invalid or revoked API key.","code":"INVALID_API_KEY"}}}}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"message":"Job not found.","code":"NOT_FOUND"}}}}},"RateLimited":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"message":"Too many requests. Please slow down.","code":"RATE_LIMITED"}}}}}}}}