{ "openapi": "3.1.0", "info": { "title": "Kardow Public API", "description": "Public API for jobs and member automation on Kardow.", "version": "1.0.0", "contact": { "name": "Kardow Support", "email": "support@kardow.com", "url": "https://kardow.com" } }, "servers": [ { "url": "https://api.kardow.com", "description": "Production API" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/jobs": { "get": { "summary": "Get Jobs", "description": "Retrieve jobs for your organization with search, filtering, and pagination.", "operationId": "getJobs", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "job_types", "in": "query", "required": false, "description": "Comma-separated job types.", "schema": { "type": "string", "example": "full-time,contract" } }, { "name": "locations", "in": "query", "required": false, "description": "Comma-separated locations.", "schema": { "type": "string", "example": "Remote,New York" } }, { "name": "categories", "in": "query", "required": false, "description": "Comma-separated category UUIDs.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000,123e4567-e89b-12d3-a456-426614174001" } }, { "name": "is_remote", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "posted_within", "in": "query", "required": false, "description": "Only jobs posted within a recent window. Use 7d for \"this week\".", "schema": { "type": "string", "enum": [ "24h", "7d", "14d", "30d", "90d" ] } }, { "name": "date_from", "in": "query", "required": false, "description": "Only jobs posted on or after this ISO 8601 date. Combine with date_to for a custom range.", "schema": { "type": "string", "example": "2026-07-01" } }, { "name": "date_to", "in": "query", "required": false, "description": "Only jobs posted on or before this ISO 8601 date.", "schema": { "type": "string", "example": "2026-07-31" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobsListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "summary": "Create Job", "description": "Create a job in your organization from an external system.", "operationId": "createJob", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" }, "examples": { "minimal": { "summary": "Minimal job", "value": { "title": "Backend Engineer", "description": "Build internal and public APIs.", "company_name": "Acme" } }, "remote_salary": { "summary": "Remote role with salary", "value": { "title": "Senior Product Designer", "description": "Lead product design across web and mobile.", "company_name": "Acme", "is_remote": true, "job_type": "full-time", "salary_min": 90000, "salary_max": 120000, "salary_currency": "USD", "salary_period": "yearly", "contact_email": "jobs@acme.com" } }, "external_apply": { "summary": "External apply flow", "value": { "title": "Growth Marketer", "description": "Own paid acquisition and lifecycle campaigns.", "company_name": "Acme", "location": "Remote", "how_to_apply": "https://acme.com/careers/growth-marketer", "how_to_apply_method": "form-external", "company_website": "https://acme.com", "status": "pending" } } } } } }, "responses": { "200": { "description": "Job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/jobs/{id}": { "get": { "summary": "Get Job", "description": "Fetch a single job by ID for your organization.", "operationId": "getJob", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Job UUID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "summary": "Update Job", "description": "Update status or editable fields on an existing job.", "operationId": "updateJob", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Job UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobRequest" }, "examples": { "approve_job": { "summary": "Approve a pending job", "value": { "status": "active" } }, "update_details": { "summary": "Update title and location", "value": { "title": "Senior Backend Engineer", "location": "Remote", "is_remote": true } } } } } }, "responses": { "200": { "description": "Job updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete Job", "description": "Permanently delete a job. This cannot be undone. To take a job offline without deleting it, PATCH its status to expired instead.", "operationId": "deleteJob", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Job UUID." } ], "responses": { "200": { "description": "Job deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/applications": { "get": { "summary": "Get Applications", "description": "List applications for jobs owned by your organization.", "operationId": "getApplications", "tags": [ "Applications" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter to applications for a specific job UUID." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "reviewed", "shortlisted", "rejected", "hired" ] }, "description": "Filter by application status." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationsListResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks": { "post": { "summary": "Subscribe to Webhooks", "description": "Create a webhook subscription for an event or return the existing matching subscription.", "operationId": "createWebhookSubscription", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookSubscriptionRequest" }, "examples": { "all_events": { "summary": "Subscribe to all events", "value": { "event": "*", "target_type": "webhook", "target_url": "https://example.com/kardow/webhook", "secret": "replace-with-a-16-char-secret" } }, "zapier_job_created": { "summary": "Subscribe a Zapier hook to job.created", "value": { "event": "job.created", "target_type": "webhook", "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/" } } } } } }, "responses": { "200": { "description": "Existing subscription returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "201": { "description": "Subscription created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "summary": "List Webhooks", "description": "List webhook subscriptions for your organization.", "operationId": "listWebhookSubscriptions", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionsListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}": { "patch": { "summary": "Update Webhook", "description": "Enable or disable an existing webhook subscription.", "operationId": "updateWebhookSubscription", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete Webhook", "description": "Delete a webhook subscription.", "operationId": "deleteWebhookSubscription", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription UUID." } ], "responses": { "200": { "description": "Subscription deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookSubscriptionResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members/sync": { "post": { "summary": "Sync Member", "description": "Create or update a member, optionally syncing access and a payment in the same request.", "operationId": "syncMember", "tags": [ "Members" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncMemberRequest" }, "examples": { "basic_member": { "summary": "Create basic member", "value": { "email": "member@example.com", "name": "Taylor Member", "role": "employee" } }, "approval_fields": { "summary": "Employer with approval and custom fields", "value": { "email": "owner@example.com", "role": "business", "customFields": { "company_size": "51-200", "website": "https://example.com" } } }, "paywall_access": { "summary": "Create member with paywall access", "value": { "email": "subscriber@example.com", "role": "employee", "access": { "stripePriceId": "price_paywall_monthly", "status": "active" } } }, "bundle_and_payment": { "summary": "Bundle quota plus payment record", "value": { "email": "poster@example.com", "role": "business", "approvalStatus": "approved", "access": { "stripePriceId": "price_bundle_10", "status": "active" }, "payment": { "jobId": "44444444-4444-4444-4444-444444444444", "amount": 199, "currency": "USD", "status": "completed", "paymentProvider": "invoice" } } } } } } }, "responses": { "200": { "description": "Updated existing member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncMemberResponse" } } } }, "201": { "description": "Created member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncMemberResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members/access": { "post": { "summary": "Member Access Action", "description": "Apply a lifecycle action to a member subscription or fully remove a board member while preserving the shared auth account.", "operationId": "memberAccessAction", "tags": [ "Members" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberAccessActionRequest" }, "examples": { "expire_now": { "summary": "Expire access now", "value": { "email": "member@example.com", "action": "expire_now", "stripeSubscriptionId": "sub_123" } }, "cancel_period_end": { "summary": "Cancel at period end", "value": { "email": "member@example.com", "action": "cancel_at_period_end", "stripeSubscriptionId": "sub_123", "effectiveAt": "2026-04-09T12:00:00.000Z" } }, "activate_new": { "summary": "Activate access", "value": { "email": "member@example.com", "action": "activate", "stripePriceId": "price_paywall_monthly", "startsAt": "2026-03-10T12:00:00.000Z" } }, "delete_member": { "summary": "Delete member from this board", "value": { "email": "member@example.com", "action": "delete_member" } } } } } }, "responses": { "200": { "description": "Subscription updated or member removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberAccessActionResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members/{lookup}": { "get": { "summary": "Get Member", "description": "Fetch member profile, subscriptions, payments, and paywall summary using email or member UUID.", "operationId": "getMember", "tags": [ "Members" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "lookup", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Member email or member UUID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMemberResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/cms": { "get": { "summary": "List CMS Collections", "description": "List every CMS collection in your organization.", "operationId": "listCmsCollections", "tags": [ "CMS" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/CmsCollection" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "summary": "Create or Update CMS Collection", "description": "Upserts a CMS collection by slug. The schema array defines the fields each item in the collection must (or may) provide.", "operationId": "upsertCmsCollection", "tags": [ "CMS" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsCollectionInput" }, "examples": { "sponsors": { "summary": "A sponsors collection", "value": { "slug": "sponsors", "name": "Sponsors", "visibility": "public", "schema": [ { "name": "name", "type": "text", "required": true }, { "name": "logo", "type": "image", "required": true }, { "name": "url", "type": "url" }, { "name": "tier", "type": "select", "options": [ "bronze", "silver", "gold" ] } ], "rules": { "allow_public_submit": false, "moderation": "manual" } } } } } } }, "responses": { "200": { "description": "Created or updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "collection": { "$ref": "#/components/schemas/CmsCollection" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/cms/{slug}": { "get": { "summary": "List CMS Items", "description": "List items inside a CMS collection.", "operationId": "listCmsItems", "tags": [ "CMS" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "pending_review", "published", "expired", "archived" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 500 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CmsItem" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "summary": "Create CMS Item", "description": "Inserts (or upserts when `id` is provided) an item in a CMS collection. The `data` object is validated against the collection's schema.", "operationId": "createCmsItem", "tags": [ "CMS" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsItemInput" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/CmsItem" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "summary": "Delete CMS Collection", "description": "Permanently deletes the collection and every item inside it.", "operationId": "deleteCmsCollection", "tags": [ "CMS" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/cms/{slug}/{id}": { "get": { "summary": "Get CMS Item", "operationId": "getCmsItem", "tags": [ "CMS" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/CmsItem" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "summary": "Update CMS Item", "operationId": "updateCmsItem", "tags": [ "CMS" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "draft", "pending_review", "published", "expired", "archived" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "position": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/CmsItem" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "summary": "Delete CMS Item", "operationId": "deleteCmsItem", "tags": [ "CMS" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/pages": { "get": { "summary": "List Pages", "description": "List custom pages and blog posts (both are custom_pages rows).", "operationId": "listPages", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "blog_post, page, or all (default).", "schema": { "type": "string", "enum": [ "blog_post", "page", "all" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "published", "archived" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PageSummary" } }, "meta": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "summary": "Create Page", "description": "Create a custom page or blog post. Send content as HTML (recommended) or TipTap JSON.", "operationId": "createPage", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageWriteRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Page" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/pages/{id}": { "get": { "summary": "Get Page", "description": "Fetch a single page or blog post, including its body as content (TipTap JSON), content_html, and content_text.", "operationId": "getPage", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Page" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "summary": "Update Page", "description": "Update a page or blog post. Only the fields you send are changed. Passing content replaces the body.", "operationId": "updatePage", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageWriteRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Page" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "summary": "Delete Page", "operationId": "deletePage", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/assets": { "get": { "summary": "List Assets", "description": "List/search the media library. URLs are always cdn.kardow.com links.", "operationId": "listAssets", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "image", "video", "file" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "meta": { "type": "object" } } } } } } } }, "post": { "summary": "Upload Asset", "description": "Add an image by URL (JSON body { source_url }) or by uploading a file (multipart/form-data with a file field). Returns a hosted cdn.kardow.com URL.", "operationId": "uploadAsset", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_url": { "type": "string", "description": "Remote image URL to import." }, "title": { "type": "string" } }, "required": [ "source_url" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "title": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Asset" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/authors": { "get": { "summary": "List Authors", "operationId": "listAuthors", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Author" } } } } } } } } }, "post": { "summary": "Create Author", "operationId": "createAuthor", "tags": [ "Content" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Author" } } } } } } } } }, "/categories": { "get": { "summary": "List Categories", "operationId": "listCategories", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } } } }, "post": { "summary": "Create Category", "description": "Idempotent: returns the existing category id if the name already exists.", "operationId": "createCategory", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } }, "/locations": { "get": { "summary": "List Locations", "description": "List the org's normalized, geocoded locations (behind location landing pages). Read-only; created automatically when jobs are posted with a location.", "operationId": "listLocations", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "meta": { "type": "object" } } } } } } } }, "post": { "summary": "Resolve Location", "description": "Turn free text into a specific place on this board. Without `create` it previews candidates and writes nothing; with `create: true` it commits the best match and returns its id for use as `location_id` on a job. Street addresses resolve to their parent city. Lookup order is the board existing locations, then a shared geocode cache, then the geocoder, so repeats and places you already cover cost nothing.", "operationId": "resolveLocation", "tags": [ "Jobs" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Place description: a city, a full street address, a postal code, or \"Remote\"." }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Two-letter country code to disambiguate, e.g. \"ca\"." }, "create": { "type": "boolean", "default": false, "description": "true commits the best match and returns its id." }, "limit": { "type": "integer", "default": 5, "maximum": 10 } } } } } }, "responses": { "200": { "description": "Candidate matches (create was false, or the place already existed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LocationCandidate" } }, "meta": { "type": "object", "properties": { "query": { "type": "string" }, "created": { "type": "boolean" }, "ambiguous": { "type": "boolean", "description": "True when several plausible matches exist and the first should not be used unattended." } } } } } } } }, "201": { "description": "Location created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Location" } } } } } }, "404": { "description": "No place found for the query" }, "422": { "description": "The value was refused as a browsable place (street address or placeholder text)" } } } }, "/users": { "get": { "summary": "List Users", "description": "List job board users (job seekers and employers) with custom signup fields projected into readable keys. Requires members:read scope.", "operationId": "listUsers", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "employee", "business", "both" ] } }, { "name": "approval_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "type": "object" } } } } } }, "403": { "$ref": "#/components/responses/ForbiddenError" } } } }, "/users/{userId}": { "get": { "summary": "Get User", "operationId": "getUser", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/users/fields": { "get": { "summary": "Get User Fields", "description": "The org's custom signup field schema. Pass format=zapier for Zapier outputFields shape.", "operationId": "getUserFields", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "zapier" ] } } ], "responses": { "200": { "description": "Success" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for authentication. Get yours from Settings > API Keys in the Kardow dashboard." } }, "schemas": { "PageSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string", "description": "blog_post or standard" }, "is_blog_article": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "url": { "type": "string", "description": "Full public URL on the live board." }, "cover_image": { "type": [ "string", "null" ], "description": "cdn.kardow.com URL." }, "meta_title": { "type": [ "string", "null" ] }, "meta_description": { "type": [ "string", "null" ] }, "author_id": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Page": { "allOf": [ { "$ref": "#/components/schemas/PageSummary" }, { "type": "object", "properties": { "og_image": { "type": [ "string", "null" ] }, "content": { "type": [ "object", "null" ], "description": "Body as TipTap JSON." }, "content_html": { "type": "string", "description": "Body rendered as HTML (easiest to read/revise)." }, "content_text": { "type": "string", "description": "Body as plain text." }, "custom_fields": { "type": "object", "additionalProperties": true } } } ] }, "PageWriteRequest": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "content": { "type": "string", "description": "Body as HTML (recommended) or TipTap JSON. Supported HTML: headings, p, strong/em/s, code, ul/ol/li, blockquote, pre>code, hr, a, img, text-align, text color, and YouTube embeds (
)." }, "kind": { "type": "string", "enum": [ "blog_post", "page" ], "description": "blog_post for a blog article, page for a standalone page." }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "slug": { "type": "string", "description": "Auto-generated from title if omitted." }, "cover_image": { "type": "string", "description": "Cover image URL, ideally from the Assets API." }, "meta_title": { "type": "string" }, "meta_description": { "type": "string", "description": "SEO description; also the blog card summary." }, "author_id": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "additionalProperties": true } } }, "Asset": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "image", "video", "file" ] }, "provider": { "type": "string" }, "url": { "type": "string", "description": "Public cdn.kardow.com URL." }, "thumbnail_url": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "visibility": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Author": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "Location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "state_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "meta_title": { "type": [ "string", "null" ] }, "meta_description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "User": { "type": "object", "description": "A job board user (job seeker or employer). Custom signup fields appear as additional readable keys.", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": [ "string", "null" ], "format": "email" }, "name": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ], "enum": [ "employee", "business", "both", null ] }, "approval_status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "profile_picture": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "CmsField": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "Snake-case identifier. Must match `^[a-z][a-z0-9_]{0,63}$`." }, "label": { "type": "string", "description": "Optional human label shown in UIs." }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "boolean", "image", "url", "select", "date" ] }, "required": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "string" }, "description": "Required when `type=select`." }, "max_length": { "type": "integer" }, "min": { "type": "number" }, "max": { "type": "number" }, "default": { "description": "Default value when none is provided." } } }, "CmsCollectionInput": { "type": "object", "required": [ "slug", "name", "schema" ], "properties": { "slug": { "type": "string", "description": "URL-safe identifier. `^[a-z][a-z0-9_-]{0,63}$`." }, "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "gated", "private" ], "default": "public" }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CmsField" }, "maxItems": 40 }, "rules": { "type": "object", "description": "Optional behavior flags.", "properties": { "allow_public_submit": { "type": "boolean", "default": false }, "moderation": { "type": "string", "enum": [ "auto", "manual" ], "default": "manual" }, "sort_by": { "type": "string", "default": "created_at" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } }, "required_entitlement": { "type": "string", "nullable": true } } }, "CmsCollection": { "allOf": [ { "$ref": "#/components/schemas/CmsCollectionInput" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "CmsItemInput": { "type": "object", "required": [ "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Provide to update an existing item." }, "data": { "type": "object", "additionalProperties": true, "description": "Validated against the collection's schema." }, "status": { "type": "string", "enum": [ "draft", "pending_review", "published", "expired", "archived" ], "default": "published" }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "owner_user_id": { "type": "string", "format": "uuid", "nullable": true } } }, "CmsItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "data": { "type": "object", "additionalProperties": true }, "status": { "type": "string" }, "source": { "type": "string", "enum": [ "manual", "payment", "api", "import" ] }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "position": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "details": {}, "url": { "type": "string" } }, "required": [ "message", "code" ] } }, "required": [ "error" ] }, "Job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "url": { "type": "string", "description": "Full public URL to the job on the live board (active custom domain when available)." }, "slug": { "type": "string", "description": "URL path only, without the domain." }, "company_name": { "type": [ "string", "null" ] }, "company_website": { "type": [ "string", "null" ] }, "company_logo_url": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "is_remote": { "type": "boolean" }, "job_type": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "category_slug": { "type": [ "string", "null" ] }, "salary_min": { "type": [ "number", "null" ] }, "salary_max": { "type": [ "number", "null" ] }, "salary_currency": { "type": [ "string", "null" ] }, "salary_period": { "type": [ "string", "null" ], "enum": [ "hourly", "daily", "weekly", "monthly", "yearly", null ] }, "how_to_apply": { "type": [ "string", "null" ], "description": "Where a candidate applies (URL, email, or phone). Not the same as url." }, "how_to_apply_method": { "type": [ "string", "null" ] }, "recruiter_name": { "type": [ "string", "null" ] }, "recruiter_url": { "type": [ "string", "null" ] }, "is_highlighted": { "type": "boolean" }, "is_sticky": { "type": "boolean" }, "source": { "type": [ "string", "null" ] }, "form_data": { "type": [ "object", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the job was posted. Alias of created_at." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "JobsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_items": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "filters": { "type": "object" } } } }, "required": [ "data", "meta" ] }, "CreateJobRequest": { "type": "object", "required": [ "title", "description", "company_name" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "company_name": { "type": "string" }, "apply_url": { "type": "string", "description": "Preferred field for the application destination — an external URL, email address, or phone number. Alias of how_to_apply (which is still accepted)." }, "apply_type": { "type": "string", "enum": [ "form-external", "website", "email", "phone", "form" ], "description": "Preferred field for how candidates apply. Alias of how_to_apply_method." }, "how_to_apply": { "type": "string", "description": "Required unless how_to_apply_method is \"form\". Where candidates apply: an external URL, an email address, or a phone number. A method of email/website/phone/form-external with no destination is rejected with 422 invalid_apply_destination." }, "how_to_apply_method": { "type": "string", "enum": [ "form-external", "website", "email", "phone", "form" ], "description": "What the apply button does: form-external, website, email, phone, or form. Must match the how_to_apply value. Only \"form\" takes no destination. Omit to auto-detect from how_to_apply." }, "posted_by_email": { "type": "string", "format": "email", "description": "Email of the employer account posting this job. Must match a job board user in the org, else the request returns 422 employer_not_found." }, "category": { "type": "string", "description": "Category name (e.g. Engineering). Matched to an existing category or created if new." }, "is_remote": { "type": "boolean" }, "is_highlighted": { "type": "boolean" }, "is_sticky": { "type": "boolean" }, "location": { "type": "string", "description": "Location shown on the job. Resolved to a real place and linked, so the job appears on the right location page and filter. Street addresses are filed under their city; exact coordinates stay on the job." }, "location_restricted": { "type": "boolean" }, "category_id": { "type": "string", "format": "uuid", "description": "Existing category UUID. Takes precedence over category if both are sent." }, "job_type": { "type": "string", "enum": [ "full-time", "part-time", "contract", "internship", "temporary", "casual" ] }, "company_website": { "type": "string", "format": "uri" }, "company_logo_url": { "type": "string", "format": "uri" }, "salary_min": { "type": "number" }, "salary_max": { "type": "number" }, "salary_currency": { "type": "string" }, "salary_period": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "yearly" ] }, "contact_email": { "type": "string", "format": "email" }, "expires_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "draft" ] }, "location_id": { "type": "string", "format": "uuid", "description": "Existing location id from POST /locations. Takes precedence over `location` text and skips resolution." }, "location_country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Two-letter country code used when resolving `location` text, e.g. \"ca\". Ignored when location_id is given." } } }, "CreateJobResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string", "description": "URL path only, without the domain." }, "url": { "type": "string", "description": "Full public URL to the created job on the live board." }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "company_logo_url": { "type": [ "string", "null" ] } } }, "meta": { "type": "object", "properties": { "organization_id": { "type": "integer" }, "board_url": { "type": "string", "description": "Base public URL of the job board." }, "url": { "type": "string", "description": "Full public URL for the created job (same as data.url)." } } } } }, "JobDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "url": { "type": "string", "description": "Full public URL to the job on the live board." }, "slug": { "type": "string", "description": "URL path only, without the domain." }, "company_name": { "type": [ "string", "null" ] }, "company_website": { "type": [ "string", "null" ] }, "company_logo_url": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "is_remote": { "type": [ "boolean", "null" ] }, "job_type": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "category_slug": { "type": [ "string", "null" ] }, "salary_min": { "type": [ "number", "null" ] }, "salary_max": { "type": [ "number", "null" ] }, "salary_currency": { "type": [ "string", "null" ] }, "salary_period": { "type": [ "string", "null" ] }, "how_to_apply": { "type": [ "string", "null" ] }, "how_to_apply_method": { "type": [ "string", "null" ] }, "recruiter_name": { "type": [ "string", "null" ] }, "recruiter_url": { "type": [ "string", "null" ] }, "is_highlighted": { "type": "boolean" }, "is_sticky": { "type": "boolean" }, "source": { "type": [ "string", "null" ], "description": "How the job was created: user, admin, scraper, api, or bulk_upload." }, "form_data": { "type": [ "object", "null" ], "description": "Custom application field values, if the board uses them." }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "JobDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" } }, "required": [ "data" ] }, "UpdateJobRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "draft", "pending", "expired" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "minLength": 1 }, "location": { "type": "string", "description": "Location shown on the job. Resolved to a real place and linked, so the job appears on the right location page and filter. Street addresses are filed under their city; exact coordinates stay on the job." }, "is_remote": { "type": "boolean" }, "location_id": { "type": "string", "format": "uuid", "description": "Existing location id from POST /locations. Takes precedence over `location` text and skips resolution." }, "location_country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Two-letter country code used when resolving `location` text, e.g. \"ca\". Ignored when location_id is given." }, "how_to_apply": { "type": "string", "description": "Required unless how_to_apply_method is \"form\". Where candidates apply: an external URL, an email address, or a phone number. A method of email/website/phone/form-external with no destination is rejected with 422 invalid_apply_destination." }, "how_to_apply_method": { "type": "string", "enum": [ "form", "form-external", "email", "website", "phone" ], "description": "What the apply button does: form-external, website, email, phone, or form. Must match the how_to_apply value. Only \"form\" takes no destination. Omit to auto-detect from how_to_apply." } }, "minProperties": 1, "additionalProperties": false }, "UpdateJobResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "is_remote": { "type": [ "boolean", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "updated_at" ] } }, "required": [ "data" ] }, "Application": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "job_title": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "applicant_name": { "type": [ "string", "null" ] }, "applicant_email": { "type": [ "string", "null" ], "format": "email" }, "applicant_phone": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "reviewed", "shortlisted", "rejected", "hired" ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "resume_url": { "type": [ "string", "null" ], "format": "uri" }, "custom_form_answers": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array" }, { "type": "null" } ] } }, "required": [ "id", "job_id", "status" ] }, "ApplicationsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_items": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "current_page", "per_page", "total_items", "total_pages", "has_more" ] } }, "required": [ "pagination" ] } }, "required": [ "data", "meta" ] }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "job.created", "job.updated", "job.approved", "job.expired", "job.deleted", "job.status_changed", "application.received", "application.status_changed", "user.created", "subscription.created", "subscription.canceled", "payment.received", "*" ] }, "target_type": { "type": "string", "enum": [ "webhook", "discord", "slack" ] }, "target_url": { "type": "string", "format": "uri" }, "is_enabled": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "event", "target_type", "target_url", "is_enabled" ] }, "CreateWebhookSubscriptionRequest": { "type": "object", "required": [ "event", "target_type", "target_url" ], "properties": { "event": { "type": "string", "enum": [ "job.created", "job.updated", "job.approved", "job.expired", "job.deleted", "job.status_changed", "application.received", "application.status_changed", "user.created", "subscription.created", "subscription.canceled", "payment.received", "*" ] }, "target_type": { "type": "string", "enum": [ "webhook", "discord", "slack" ] }, "target_url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "minLength": 16 } }, "additionalProperties": false }, "WebhookSubscriptionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } }, "required": [ "data" ] }, "WebhookSubscriptionsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } }, "required": [ "total" ] } }, "required": [ "data", "meta" ] }, "UpdateWebhookSubscriptionRequest": { "type": "object", "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean" } }, "additionalProperties": false }, "DeleteWebhookSubscriptionResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] }, "Member": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "integer" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "role": { "type": "string" }, "approvalStatus": { "type": "string" }, "authMethod": { "type": [ "string", "null" ], "description": "How the member authenticates (e.g. password, oauth)." }, "profilePicture": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "customFields": { "type": [ "object", "null" ], "additionalProperties": true } } }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "integer" }, "userId": { "type": "string", "format": "uuid" }, "planId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "stripeSubscriptionId": { "type": [ "string", "null" ] }, "currentPeriodStart": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "jobsRemaining": { "type": [ "integer", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "integer" }, "userId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "planId": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "paymentProvider": { "type": [ "string", "null" ] }, "stripeSessionId": { "type": [ "string", "null" ] }, "stripePaymentIntentId": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "SyncMemberRequest": { "type": "object", "required": [ "email" ], "properties": { "userId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "employee", "business", "both", "jobseeker", "employer" ] }, "approvalStatus": { "type": "string", "enum": [ "approved", "pending", "rejected" ] }, "profilePicture": { "type": [ "string", "null" ], "format": "uri" }, "description": { "type": [ "string", "null" ] }, "customFields": { "type": [ "object", "null" ], "additionalProperties": true }, "access": { "type": "object", "properties": { "planId": { "type": "string", "format": "uuid" }, "stripePriceId": { "type": "string" }, "paypalPlanId": { "type": "string" }, "planName": { "type": "string" }, "subscriptionId": { "type": "string", "format": "uuid" }, "stripeSubscriptionId": { "type": "string" }, "status": { "type": "string", "default": "active" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "jobsRemaining": { "type": [ "integer", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "payment": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "planId": { "type": "string", "format": "uuid" }, "stripePriceId": { "type": "string" }, "paypalPlanId": { "type": "string" }, "planName": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "paymentProvider": { "type": [ "string", "null" ] }, "stripeSessionId": { "type": [ "string", "null" ] }, "stripePaymentIntentId": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } }, "required": [ "jobId", "amount", "currency" ] } } }, "SyncMemberResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/Member" }, "access": { "oneOf": [ { "$ref": "#/components/schemas/Subscription" }, { "type": "null" } ] }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/Payment" }, { "type": "null" } ] }, "created": { "type": "boolean" } }, "required": [ "member", "created" ] } }, "required": [ "data" ] }, "MemberAccessActionRequest": { "type": "object", "required": [ "action" ], "properties": { "email": { "type": "string", "format": "email" }, "userId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "activate", "delete_member", "expire_now", "cancel_now", "cancel_at_period_end", "reactivate", "mark_past_due" ] }, "planId": { "type": "string", "format": "uuid" }, "stripePriceId": { "type": "string" }, "paypalPlanId": { "type": "string" }, "planName": { "type": "string" }, "subscriptionId": { "type": "string", "format": "uuid" }, "stripeSubscriptionId": { "type": "string" }, "effectiveAt": { "type": "string", "format": "date-time" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "jobsRemaining": { "type": [ "integer", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "DeleteMemberActionResult": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "userId": { "type": "string", "format": "uuid" }, "organizationId": { "type": "integer" }, "removedSubscriptionCount": { "type": "integer" }, "cleanupErrors": { "type": "array", "items": { "type": "string" } } }, "required": [ "deleted", "userId", "organizationId", "removedSubscriptionCount" ] }, "MemberAccessActionResponse": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/Subscription" }, { "$ref": "#/components/schemas/DeleteMemberActionResult" } ] } }, "required": [ "data" ] }, "GetMemberResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/Member" }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "hasValidPaywallSubscription": { "type": "boolean" } }, "required": [ "member", "subscriptions", "payments", "hasValidPaywallSubscription" ] } }, "required": [ "data" ] }, "LocationCandidate": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid", "description": "Location entity id, or null when this place is not on the board yet." }, "display_name": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "state_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "location_type": { "type": "string" }, "full_address": { "type": [ "string", "null" ], "description": "Street-level address that matched, when the query was an address." }, "mapbox_id": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "existing", "cache", "geocoded", "remote" ] }, "confidence": { "type": "string", "enum": [ "exact", "high", "low" ] } } } }, "responses": { "ValidationError": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "UnauthorizedError": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ForbiddenError": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFoundError": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimitError": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }