{ "openapi": "3.1.0", "info": { "title": "AllRoles Developer API", "version": "1.0.0", "description": "Programmatic access to the AllRoles postings dataset: current postings, the company registry, the lifecycle event feed, point-in-time snapshots (history begins 2026-10-15) and bulk CSV exports. Authenticate with an API key (Data Team plan) as 'Authorization: Bearer ar_live_…'." }, "servers": [ { "url": "https://allroles.lovable.app" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ar_live_<48 hex>" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] }, "Job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "company": { "type": "string" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "company_domain": { "type": [ "string", "null" ] }, "location": { "type": "string" }, "country": { "type": "string" }, "seniority": { "type": [ "string", "null" ], "enum": [ "intern", "entry", "mid", "senior", "staff_principal", "manager", "director", "vp_executive", null ] }, "role_family": { "type": "string" }, "workplace_type": { "type": [ "string", "null" ], "enum": [ "remote", "hybrid", "onsite", null ] }, "is_ai_role": { "type": "boolean" }, "is_early_career": { "type": "boolean" }, "salary_min": { "type": [ "number", "null" ] }, "salary_max": { "type": [ "number", "null" ] }, "salary_currency": { "type": [ "string", "null" ] }, "salary_period": { "type": [ "string", "null" ] }, "description_excerpt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Only with ?include=description." }, "url": { "type": "string", "format": "uri" }, "posted_at": { "type": "string", "format": "date-time" }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "tags_version": { "type": "integer" }, "active": { "type": "boolean" } } }, "Company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "domain_source": { "type": [ "string", "null" ] }, "ats": { "type": "string" }, "board_id": { "type": [ "string", "null" ] }, "registry_active": { "type": "boolean" }, "verification": { "type": "string" }, "last_job_count": { "type": "integer" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "active_postings": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "Change": { "type": "object", "properties": { "id": { "type": "integer" }, "job_id": { "type": [ "string", "null" ], "format": "uuid" }, "company": { "type": "string" }, "type": { "type": "string", "enum": [ "first_seen", "field_change", "closed", "reopened" ] }, "field": { "type": [ "string", "null" ] }, "old_value": { "type": [ "string", "null" ] }, "new_value": { "type": [ "string", "null" ] }, "close_reason": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "occurred_at": { "type": "string", "format": "date-time" } } } }, "parameters": { "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, "Cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's meta.next_cursor.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Unknown id or date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit exceeded; see the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/api/v1/jobs": { "get": { "summary": "List postings", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "company", "in": "query", "schema": { "type": "string" }, "description": "Registry company name or company_id (UUID)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Title contains (case-insensitive)." }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "US" }, { "name": "seniority", "in": "query", "schema": { "type": "string", "enum": [ "intern", "entry", "mid", "senior", "staff_principal", "manager", "director", "vp_executive" ] } }, { "name": "workplace_type", "in": "query", "schema": { "type": "string", "enum": [ "remote", "hybrid", "onsite" ] } }, { "name": "is_ai_role", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_early_career", "in": "query", "schema": { "type": "boolean" } }, { "name": "salary_min", "in": "query", "schema": { "type": "number" }, "description": "Annualized USD at least (midpoint of the advertised range, scaled by pay period)." }, { "name": "posted_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "posted_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "first_seen_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "active", "in": "query", "schema": { "type": "boolean", "default": true } }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "description" ] }, "description": "include=description returns the full posting body (license terms apply)." } ], "responses": { "200": { "description": "A page of postings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "meta": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date-time" }, "count": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/jobs/{id}": { "get": { "summary": "One posting", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "description" ] } } ], "responses": { "200": { "description": "The posting", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/companies": { "get": { "summary": "List registry companies", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Name contains (case-insensitive)." }, { "name": "has_domain", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A page of companies", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/companies/{id}": { "get": { "summary": "One company plus current hiring stats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The company, with a stats object (active, new7d, closed7d)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Company" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/changes": { "get": { "summary": "Lifecycle event feed (job_events)", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Default: 24 hours ago. May not be more than 31 days ago." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "first_seen", "field_change", "closed", "reopened" ] } }, { "name": "company_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "field", "in": "query", "schema": { "type": "string" }, "description": "For field_change events: the changed field (e.g. salary_max)." } ], "responses": { "200": { "description": "A page of events, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/snapshots": { "get": { "summary": "List available snapshot dates", "responses": { "200": { "description": "Dates with row counts, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "rows": { "type": "integer" }, "active_rows": { "type": "integer" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/snapshots/{date}": { "get": { "summary": "The board as it stood on a date", "parameters": [ { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of snapshot rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/exports/jobs.csv": { "get": { "summary": "Bulk CSV export (costs 10 rate-limit tokens)", "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Snapshot date; omit for the live board." } ], "responses": { "200": { "description": "CSV with a #-comment manifest header; X-Export-Rows / X-Export-Sha256 / X-Export-Generated-At / X-Export-As-Of headers carry the same manifest.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }