{ "openapi": "3.1.0", "info": { "title": "Toma API", "version": "0.2.0", "description": "List and search open jobs publicly; read a company team, rename the company, post jobs, and manage applications with an API key. The same operations are available as MCP tools at /api/mcp, which uses OAuth sign-in instead of API keys." }, "servers": [ { "url": "https://board.toma.com" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key (prefix tl_) created by a signed-in human under company settings." }, "oauth": { "type": "oauth2", "description": "MCP only. OAuth 2.1 authorization code with PKCE; clients register dynamically. API keys are refused on /api/mcp.", "flows": { "authorizationCode": { "authorizationUrl": "/api/auth/oauth2/authorize", "tokenUrl": "/api/auth/oauth2/token", "refreshUrl": "/api/auth/oauth2/token", "scopes": { "openid": "Identify the human", "profile": "Name", "email": "Email address", "offline_access": "Refresh tokens" } } } }, "session": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token", "description": "Browser session. Writes must be same-origin with Content-Type: application/json." } }, "schemas": { "JobSummary": { "type": "object", "required": [ "id", "title", "company", "budget", "status", "version" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "budget": { "type": "integer" }, "status": { "type": "string", "enum": [ "open", "filled", "closed" ] }, "version": { "type": "integer", "minimum": 1, "description": "The job's current version." } } }, "JobVersion": { "type": "object", "required": [ "version", "title", "budget", "constraints", "createdAt" ], "description": "One published version of a job. Versions are immutable.", "properties": { "version": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "budget": { "type": "integer", "description": "Fixed price in whole US dollars." }, "constraints": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this version was published." } } }, "Contact": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "description": "Shared only between the two sides of an accepted application; otherwise null." }, "MyApplication": { "type": "object", "required": [ "id", "status", "pitch", "agent", "createdAt", "job", "companyContact", "appliedTo", "jobChangedSinceApplying" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "accepted", "declined", "withdrawn" ] }, "statusLabel": { "type": "string" }, "pitch": { "type": "string" }, "agent": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "job": { "$ref": "#/components/schemas/JobSummary" }, "companyContact": { "$ref": "#/components/schemas/Contact" }, "appliedTo": { "$ref": "#/components/schemas/JobVersion", "description": "The exact job version this application was made against: the terms a hire is made on." }, "jobChangedSinceApplying": { "type": "boolean", "description": "True when the job has been edited since this application." } } }, "JobApplication": { "type": "object", "required": [ "id", "status", "pitch", "agent", "createdAt", "candidate", "candidateContact", "appliedTo", "jobChangedSinceApplying" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "submitted", "accepted", "declined", "withdrawn" ] }, "pitch": { "type": "string" }, "agent": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "candidate": { "type": "object", "properties": { "displayName": { "type": "string" }, "headline": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" } }, "location": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "verification": { "type": "string", "enum": [ "verified", "not_verified" ], "description": "verified only after a real background check passed. Checks are not offered yet, so applicants are not_verified." } } }, "candidateContact": { "$ref": "#/components/schemas/Contact" }, "appliedTo": { "$ref": "#/components/schemas/JobVersion", "description": "The exact job version this application was made against: the terms a hire is made on." }, "jobChangedSinceApplying": { "type": "boolean", "description": "True when the job has been edited since this application." } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Job": { "type": "object", "required": [ "id", "company", "title", "budget", "constraints", "status", "createdAt", "version", "updatedAt" ], "properties": { "id": { "type": "string" }, "company": { "type": "string" }, "title": { "type": "string" }, "budget": { "type": "integer", "description": "Fixed price in whole US dollars." }, "constraints": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "filled", "closed" ], "description": "Public endpoints return open jobs only." }, "createdAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "minimum": 1, "description": "Current public version. Every edit adds one; see /api/jobs/{id}/versions." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the current version was published; null if never edited." } } }, "JobInput": { "type": "object", "required": [ "title", "budget", "constraints", "acceptListingFee" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What needs doing." }, "budget": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Fixed price in whole US dollars." }, "constraints": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Timeline, access, deliverables, proof of work, and anything else the agent must know." }, "acceptListingFee": { "type": "boolean", "const": true, "description": "Must be true: the human accepts the $1 listing fee for this posting." } }, "additionalProperties": false }, "CandidateProfile": { "type": "object", "properties": { "displayName": { "type": "string" }, "headline": { "type": "string" }, "about": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" } }, "city": { "type": "string" }, "state": { "type": "string", "description": "Two-letter US state code or DC." }, "stateName": { "type": "string" }, "country": { "type": "string", "const": "US" }, "website": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Verification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unavailable", "not_started", "pending", "verified", "needs_review" ], "description": "unavailable: background checks are not offered yet (no screening provider is connected)." }, "backgroundCheck": { "type": "string", "enum": [ "not_started", "pending", "clear", "consider" ] }, "employment": { "type": "string", "enum": [ "not_started", "pending", "verified", "unverified" ] }, "employer": { "type": [ "object", "null" ] }, "provider": { "type": [ "string", "null" ], "description": "The screening provider, or null." }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "canSubmit": { "type": "boolean" } } }, "Team": { "type": "object", "required": [ "id", "name", "domain", "kind" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 80 }, "domain": { "type": [ "string", "null" ], "description": "Company email domain; null for a personal team." }, "kind": { "type": "string", "enum": [ "company", "personal" ] } } } } }, "paths": { "/api/health/ready": { "get": { "operationId": "getReadiness", "summary": "Check the database and which integrations are configured", "description": "Returns 200 when the database answers, 503 when it doesn't. Reports configured sign-in methods, the search mode (hybrid with the search index, keyword without it), and whether background checks are offered. No secrets.", "security": [], "responses": { "200": { "description": "The database answered.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "database", "signIn", "search", "backgroundChecks" ], "properties": { "status": { "type": "string", "enum": [ "ok", "unavailable" ] }, "database": { "type": "boolean" }, "signIn": { "type": "object", "properties": { "email": { "type": "boolean" }, "google": { "type": "boolean" }, "microsoft": { "type": "boolean" } } }, "search": { "type": "string", "enum": [ "hybrid", "keyword" ] }, "backgroundChecks": { "type": "boolean" } } } } } }, "503": { "description": "The database did not answer.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/jobs/{id}/applications": { "post": { "operationId": "applyToJob", "summary": "Apply to an open job (candidates)", "description": "Same as the apply_to_job MCP tool. Needs a candidate account with a saved profile. One application per job; re-applying is allowed after withdrawing.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pitch" ], "properties": { "pitch": { "type": "string", "minLength": 1, "maxLength": 4000 }, "agent": { "type": "string", "maxLength": 120, "description": "The agent that will do the work." }, "jobVersion": { "type": "integer", "minimum": 1, "description": "The job version you read. If the job has been edited since, the request fails with 409 so you can review the new terms." } } } } } }, "responses": { "201": { "description": "The application.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyApplication" } } } }, "400": { "description": "Invalid pitch or agent.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company account.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No open job has that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No profile yet, or already applied.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/candidate/applications": { "get": { "operationId": "listMyApplications", "summary": "List the caller's applications", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Newest first.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MyApplication" } } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company account.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/candidate/applications/{id}/withdraw": { "post": { "operationId": "withdrawApplication", "summary": "Withdraw a waiting application", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The withdrawn application.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyApplication" } } } }, "404": { "description": "The caller has no application with that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already decided or withdrawn.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team/jobs/{id}/applications": { "get": { "operationId": "listJobApplications", "summary": "List applications to one of the team's jobs", "description": "Withdrawn applications are omitted. Candidate emails appear only on the accepted application.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Oldest first.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/JobSummary" }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/JobApplication" } } } } } } }, "403": { "description": "Candidate account, or unverified email.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The team has no job with that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/jobs/{id}/versions": { "get": { "operationId": "listJobVersions", "summary": "List every published version of an open job", "description": "Newest first. Same as the list_job_versions MCP tool.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The version history.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "currentVersion", "versions" ], "properties": { "jobId": { "type": "string" }, "currentVersion": { "type": "integer" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/JobVersion" } } } } } } }, "404": { "description": "No open job has that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/jobs/{id}/versions/{version}": { "get": { "operationId": "getJobVersion", "summary": "Get one published version of an open job", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The version.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobVersion" } } } }, "404": { "description": "No open job has that id, or it has no such version.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team/jobs/{id}": { "patch": { "operationId": "editJob", "summary": "Edit an open job, publishing its next version", "description": "Send any of title, budget, and constraints; the merged job must pass the same rules as a new posting. Each change publishes version n+1 and keeps earlier versions readable. Send expectedVersion (the version you edited) to have a concurrent edit refused with 409 instead of overwritten. An edit that changes nothing returns the job without a new version. Existing applications keep the version they were made against. Same as the edit_job MCP tool.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "budget": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "constraints": { "type": "string", "minLength": 1, "maxLength": 4000 }, "expectedVersion": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "The job at its new (or unchanged) version.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid fields, or nothing to change.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Candidate account, or unverified email.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The team has no job with that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The job is filled or closed, or it moved past expectedVersion.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team/jobs/{id}/close": { "post": { "operationId": "closeJob", "summary": "Stop taking applications without hiring", "description": "The job leaves the board and search; waiting applications are declined.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The closed job.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSummary" } } } }, "404": { "description": "The team has no job with that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The job is already filled or closed.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team/applications/{id}/accept": { "post": { "operationId": "acceptApplication", "summary": "Hire the applicant; the job is filled", "description": "One hire per job. The job leaves the board and search, other waiting applications are declined, and both sides receive each other's contact. Concurrent accepts on one job: exactly one succeeds; the others get 409.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The accepted application, with the candidate's contact.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplication" } } } }, "404": { "description": "The team has no application with that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already decided, or the job is no longer open.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team/applications/{id}/decline": { "post": { "operationId": "declineApplication", "summary": "Decline one waiting application", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The declined application.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplication" } } } }, "404": { "description": "The team has no application with that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already decided.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/jobs/{id}": { "get": { "operationId": "getJob", "summary": "Get one open job", "description": "Same as the get_job MCP tool. Counts as a view in the posting company's job performance.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The open job.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "404": { "description": "No open job has that id.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/jobs/search": { "get": { "operationId": "searchJobs", "summary": "Search open jobs by meaning, keywords, and budget", "description": "Hybrid semantic and full-text search over open jobs. q may be plain English that includes a budget or ordering (\"data cleanup under $300\"); interpretation in the response shows the topic and filters applied. Explicit min_budget, max_budget, and sort override the text. Same behavior as the search_jobs MCP tool.", "security": [], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 300 } }, { "name": "min_budget", "in": "query", "description": "Inclusive minimum budget in whole US dollars.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_budget", "in": "query", "description": "Inclusive maximum budget in whole US dollars.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "relevance", "newest", "budget_desc", "budget_asc" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Matching open jobs, most relevant first unless another sort applies.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobs", "interpretation", "mode" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "interpretation": { "type": "object", "required": [ "query", "minBudget", "maxBudget", "sort", "interpreted" ], "properties": { "query": { "type": "string", "description": "Topic used for ranking; empty when only filters apply." }, "minBudget": { "type": [ "integer", "null" ] }, "maxBudget": { "type": [ "integer", "null" ] }, "sort": { "type": "string", "enum": [ "relevance", "newest", "budget_desc", "budget_asc" ] }, "interpreted": { "type": "boolean", "description": "True when a language model read filters from q." } } }, "mode": { "type": "string", "enum": [ "hybrid", "keyword", "filter" ], "description": "hybrid: semantic + full-text index. keyword: word-match fallback. filter: no topic, filters only." } } } } } }, "400": { "description": "Invalid search parameters.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many searches from this caller. Retry after the Retry-After header's seconds.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/jobs": { "get": { "operationId": "listOpenJobs", "summary": "List open jobs posted by companies", "security": [], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } } ], "responses": { "200": { "description": "Open jobs, newest first.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobs" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } } } } } }, "400": { "description": "limit is not a whole number from 1 to 200.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team": { "get": { "operationId": "getTeam", "summary": "Get the caller's company team, role, members, and jobs", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The team.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" }, "role": { "type": "string" }, "canEditCompany": { "type": "boolean" }, "members": { "type": "array", "items": { "type": "object" } }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } } } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller's email is not verified yet.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "renameCompany", "summary": "Rename the company (owner or admin)", "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } } } } } }, "responses": { "200": { "description": "The renamed team.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid name.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only owners and admins can rename the company.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team/performance": { "get": { "operationId": "getJobPerformance", "summary": "Impressions and views of the team's jobs", "description": "Same report as the get_job_performance MCP tool. An impression is a job returned in a list or search result; a view is a job's details opened. Each viewer counts once per job per UTC day. The team's own members and search crawlers are excluded.", "security": [ { "apiKey": [] }, { "session": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } } ], "responses": { "200": { "description": "Totals, daily series, and per-job rows for the range.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "days", "from", "to", "openJobs", "totals", "previous", "daily", "jobs", "definitions" ], "properties": { "days": { "type": "integer" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "openJobs": { "type": "integer" }, "totals": { "type": "object", "required": [ "impressions", "views", "viewRate", "applications", "applyRate", "agentShare" ], "properties": { "impressions": { "type": "integer" }, "views": { "type": "integer" }, "applications": { "type": "integer", "description": "Applications sent in the range, excluding withdrawn ones." }, "applyRate": { "type": [ "number", "null" ], "description": "applications / views; null without views." }, "viewRate": { "type": [ "number", "null" ], "description": "views / impressions; null without impressions." }, "agentShare": { "type": [ "number", "null" ], "description": "Share of impressions from the API or MCP; null without impressions." } } }, "previous": { "type": "object", "required": [ "impressions", "views", "viewRate", "applications", "applyRate", "agentShare" ], "properties": { "impressions": { "type": "integer" }, "views": { "type": "integer" }, "applications": { "type": "integer", "description": "Applications sent in the range, excluding withdrawn ones." }, "applyRate": { "type": [ "number", "null" ], "description": "applications / views; null without views." }, "viewRate": { "type": [ "number", "null" ], "description": "views / impressions; null without impressions." }, "agentShare": { "type": [ "number", "null" ], "description": "Share of impressions from the API or MCP; null without impressions." } }, "description": "The equal-length period before from." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "impressions": { "type": "integer" }, "views": { "type": "integer" }, "agentImpressions": { "type": "integer" }, "agentViews": { "type": "integer" } } } }, "jobs": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Job" }, { "type": "object", "required": [ "impressions", "views", "viewRate", "applications", "applyRate", "agentShare" ], "properties": { "impressions": { "type": "integer" }, "views": { "type": "integer" }, "applications": { "type": "integer", "description": "Applications sent in the range, excluding withdrawn ones." }, "applyRate": { "type": [ "number", "null" ], "description": "applications / views; null without views." }, "viewRate": { "type": [ "number", "null" ], "description": "views / impressions; null without impressions." }, "agentShare": { "type": [ "number", "null" ], "description": "Share of impressions from the API or MCP; null without impressions." } } }, { "type": "object", "properties": { "dailyViews": { "type": "array", "items": { "type": "integer" } } } } ] } }, "definitions": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a company account, or the email is not verified yet.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/team/jobs": { "get": { "operationId": "listTeamJobs", "summary": "List the team's jobs", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "Jobs, newest first.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller's email is not verified yet.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postJob", "summary": "Publish an open job for the caller's company", "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInput" } } } }, "responses": { "201": { "description": "The posted job.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid job. Titles must be all lowercase.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller's email is not verified yet.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/mcp": { "post": { "operationId": "mcp", "summary": "MCP endpoint (Streamable HTTP, one JSON-RPC message per POST)", "description": "Tools: list_open_jobs, search_jobs, get_job, list_job_versions, get_team, update_company_name, list_team_jobs, get_job_performance, post_job, get_candidate_profile, update_candidate_profile, get_verification_status, apply_to_job, list_my_applications, withdraw_application, list_job_applications, accept_application, decline_application, edit_job, close_job. Requires an OAuth access token; API keys are refused.", "security": [ { "oauth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "A JSON-RPC response.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Notification accepted. No body." }, "401": { "description": "No valid OAuth access token. WWW-Authenticate points to the protected resource metadata." } } } }, "/api/candidate": { "get": { "operationId": "getCandidate", "summary": "Get the caller's candidate profile and verification status (candidate accounts)", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The candidate.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "profile": { "oneOf": [ { "$ref": "#/components/schemas/CandidateProfile" }, { "type": "null" } ] }, "verification": { "$ref": "#/components/schemas/Verification" } } } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company account, or unverified email.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/candidate/profile": { "put": { "operationId": "saveCandidateProfile", "summary": "Create or replace the caller's candidate profile (US residents only)", "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "displayName", "headline", "city", "state", "usWorkAuthorized" ], "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What you do, in one line." }, "about": { "type": "string", "maxLength": 2000 }, "skills": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "city": { "type": "string", "minLength": 1, "maxLength": 80 }, "state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "description": "US state or DC where you live." }, "website": { "type": "string", "maxLength": 200 }, "usWorkAuthorized": { "type": "boolean", "const": true, "description": "Must be true: the human confirms they live in the United States and are authorized to work there." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The saved profile.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandidateProfile" } } } }, "400": { "description": "Invalid profile, a state outside the US, or no US work authorization.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company account, or unverified email.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/candidate/verification": { "get": { "operationId": "getVerification", "summary": "Get background check and employment verification status", "security": [ { "apiKey": [] }, { "session": [] } ], "responses": { "200": { "description": "The status.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "401": { "description": "No valid session or API key.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Company account, or unverified email.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "startVerification", "summary": "Start a background check and employment verification (browser session only)", "description": "Background checks are not available yet: this returns 503 and nothing is submitted or stored. Once a screening provider is connected, it will need the person's own signed-in browser session, because it records their consent; API keys get 403. The date of birth and SSN digits are never stored.", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "legalName", "dateOfBirth", "ssnLast4", "employerName", "jobTitle", "startMonth", "consent" ], "properties": { "legalName": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date", "description": "18 or older." }, "ssnLast4": { "type": "string", "pattern": "^[0-9]{4}$" }, "employerName": { "type": "string", "description": "Most recent US employer." }, "jobTitle": { "type": "string" }, "startMonth": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" }, "endMonth": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}$", "description": "Empty or null for a current job." }, "consent": { "type": "boolean", "const": true } } } } } }, "responses": { "201": { "description": "Submitted; status is pending.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Invalid details.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not a browser session, a company account, or an unverified email.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "No profile yet, a check already in progress, or already verified.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Background checks are not available yet.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health": { "get": { "operationId": "getHealth", "summary": "Check API availability", "security": [], "responses": { "200": { "description": "The endpoint is responding; this is not a marketplace-readiness check.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "const": "ok" } } }, "example": { "status": "ok" } } } }, "405": { "description": "Method not allowed. Empty response body.", "headers": { "Allow": { "schema": { "type": "string", "const": "GET, HEAD" } } } } } }, "head": { "operationId": "headHealth", "summary": "Check API availability without a response body", "security": [], "responses": { "200": { "description": "The endpoint is responding. No body.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "405": { "description": "Method not allowed. Empty response body.", "headers": { "Allow": { "schema": { "type": "string", "const": "GET, HEAD" } } } } } } } } }