{ "openapi": "3.1.0", "info": { "title": "Ur Next Door API", "version": "1.0.0", "summary": "Create and schedule posts, questions, polls, MCQs, communities, services and jobs on Ur Next Door with a personal API key.", "description": "The Ur Next Door API lets a member publish to https://urnextdoor.com from a script, an automation tool or an AI agent, with a personal API key created in Settings > API keys. Every request acts as that member, with the same permissions they have on the website. Bodies are HTML. Times are ISO 8601 and scheduling stores UTC. Full guides: https://docs.urnextdoor.com", "termsOfService": "https://urnextdoor.com/terms", "contact": { "name": "Ur Next Door support", "url": "https://docs.urnextdoor.com", "email": "support@urnextdoor.com" }, "x-burst-limit-per-minute": 60, "x-quotas": { "free": { "post": 20, "question": 20, "poll": 10, "mcq": 30, "community": 2, "service": 5, "job": 5, "media": 50 }, "pro": { "post": 60, "question": 60, "poll": 30, "mcq": 90, "community": 5, "service": 15, "job": 15, "media": 150 }, "business": { "post": 200, "question": 200, "poll": 100, "mcq": 300, "community": 20, "service": 50, "job": 50, "media": 500 } } }, "externalDocs": { "description": "Ur Next Door API Docs", "url": "https://docs.urnextdoor.com" }, "servers": [ { "description": "Production (apex domain only)", "url": "https://urnextdoor.com/api/v1" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "description": "Check which member and key a request runs as, see today's quota usage, and fetch the OpenAPI document.", "name": "Account", "x-page-title": "Account endpoints", "x-slug": "account" }, { "description": "Create posts, questions, polls, MCQs, communities, Marketplace services and jobs, now or at a scheduled time.", "name": "Content", "x-page-title": "Content endpoints", "x-slug": "content" }, { "description": "Upload an image as base64 JSON or multipart, then use the returned URL as a featured image or in a gallery.", "name": "Media", "x-page-title": "Media endpoint", "x-slug": "media" }, { "description": "List your scheduled items, move them to a new time, publish them now, or cancel them before they go live.", "name": "Scheduling", "x-page-title": "Scheduling endpoints", "x-slug": "scheduling" }, { "description": "Find the ids the create endpoints need: communities you can post in, service categories, job options, places and icons.", "name": "Lookups", "x-page-title": "Lookup endpoints", "x-slug": "lookups" } ], "paths": { "/me": { "get": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Account" ], "summary": "Who am I", "description": "Returns the member this key acts as and details of the key itself (name, prefix, scopes, expiry). Works with any valid key. Use it to test a key.", "operationId": "getMe", "x-required-scope": null, "x-quota-action": null, "responses": { "200": { "description": "The member and the key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "basic": { "summary": "A free plan member", "value": { "ok": true, "user": { "id": 7, "username": "aarav", "display_name": "Aarav", "plan": "free", "profile_url": "https://urnextdoor.com/users/aarav" }, "key": { "id": 3, "name": "Claude Code", "prefix": "und_sk_7Hq2x", "scopes": [ "content", "media", "schedule", "read" ], "created_at": "2026-10-15T09:00:00Z", "expires_at": "2027-01-13T09:00:00Z" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "421": { "$ref": "#/components/responses/WrongHost" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/usage": { "get": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Account" ], "summary": "Today's quota usage", "description": "Returns your plan, the current UTC day, when counters reset, and used and remaining counts for each action. Works with any valid key and is not quota-counted.", "operationId": "getUsage", "x-required-scope": null, "x-quota-action": null, "responses": { "200": { "description": "Usage for the current UTC day.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Three posts used today", "value": { "ok": true, "plan": "free", "day": "2026-10-15", "resets_at": "2026-10-16T00:00:00Z", "quotas": [ { "action": "post", "limit": 20, "used": 3, "remaining": 17 }, { "action": "question", "limit": 20, "used": 0, "remaining": 20 }, { "action": "media", "limit": 50, "used": 2, "remaining": 48 } ], "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "421": { "$ref": "#/components/responses/WrongHost" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/openapi.json": { "get": { "security": [], "tags": [ "Account" ], "summary": "OpenAPI document", "description": "Returns this OpenAPI 3.1 document. Public: no key needed. Import it into ChatGPT Actions, Postman or a code generator.", "operationId": "getOpenapi", "x-required-scope": null, "x-quota-action": null, "responses": { "200": { "description": "The OpenAPI document.", "headers": { "Cache-Control": { "description": "public, max-age=3600", "schema": { "type": "string" } } }, "content": { "application/json": { "examples": { "basic": { "summary": "The document (truncated)", "value": { "openapi": "3.1.0", "info": { "title": "Ur Next Door API", "version": "1.0.0" } } } }, "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "The document is not available on this server." } } } }, "/posts": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Content" ], "summary": "Create a post", "description": "Publishes a post now, or schedules it when scheduled_at is set. title and body (HTML) are required. Send an Idempotency-Key so a retry never posts twice. Counts against the post quota.", "operationId": "createPost", "x-required-scope": "content", "x-quota-action": "post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "basic": { "summary": "Publish now", "value": { "title": "Five easy ways to save water at home", "body": "

Small habits add up. These five saved our building a lot of water this summer.

", "tags": [ "water", "home" ] } }, "scheduled": { "summary": "Schedule for later", "value": { "title": "Five easy ways to save water at home", "body": "

Small habits add up. These five saved our building a lot of water this summer.

", "tags": [ "water", "home" ], "scheduled_at": "2026-10-20T09:30:00Z" } }, "withImage": { "summary": "With an uploaded image", "value": { "title": "Five easy ways to save water at home", "body": "

Small habits add up. These five saved our building a lot of water this summer.

", "featured_image": "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp", "tags": [ "water", "home" ] } } }, "schema": { "$ref": "#/components/schemas/CreatePostRequest" } } } }, "responses": { "201": { "description": "Created. Published now, or scheduled when scheduled_at was sent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Published now", "value": { "ok": true, "id": 41, "slug": "five-easy-ways-to-save-water-at-home", "url": "/posts/five-easy-ways-to-save-water-at-home", "web_url": "https://urnextdoor.com/posts/five-easy-ways-to-save-water-at-home", "item": { "id": 41, "type": "post", "slug": "five-easy-ways-to-save-water-at-home" }, "request_id": "9f8e7d6c5b4a3921" } }, "scheduled": { "summary": "Scheduled", "value": { "ok": true, "id": 41, "slug": "five-easy-ways-to-save-water-at-home", "url": "/posts/five-easy-ways-to-save-water-at-home", "web_url": "https://urnextdoor.com/posts/five-easy-ways-to-save-water-at-home", "status": "scheduled", "scheduled_at": "2026-10-20T09:30:00Z", "item": { "id": 41, "type": "post", "slug": "five-easy-ways-to-save-water-at-home" }, "request_id": "9f8e7d6c5b4a3921" } }, "withImage": { "summary": "Published with a featured image", "value": { "ok": true, "id": 41, "slug": "five-easy-ways-to-save-water-at-home", "url": "/posts/five-easy-ways-to-save-water-at-home", "web_url": "https://urnextdoor.com/posts/five-easy-ways-to-save-water-at-home", "item": { "id": 41, "type": "post", "slug": "five-easy-ways-to-save-water-at-home" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/questions": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Content" ], "summary": "Ask a question", "description": "Publishes a question now, or schedules it when scheduled_at is set. Only title is required; body (HTML) adds details. Counts against the question quota.", "operationId": "createQuestion", "x-required-scope": "content", "x-quota-action": "question", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "basic": { "summary": "Publish now", "value": { "title": "Which plants survive a north facing balcony?", "body": "

We get about two hours of direct sun. What has worked for you?

", "tags": [ "gardening" ] } }, "scheduled": { "summary": "Schedule for later", "value": { "title": "Which plants survive a north facing balcony?", "tags": [ "gardening" ], "scheduled_at": "2026-10-20T09:30:00Z" } }, "withImage": { "summary": "With an uploaded image", "value": { "title": "Which plants survive a north facing balcony?", "featured_image": "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp", "tags": [ "gardening" ] } } }, "schema": { "$ref": "#/components/schemas/CreateQuestionRequest" } } } }, "responses": { "201": { "description": "Created. Published now, or scheduled when scheduled_at was sent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Published now", "value": { "ok": true, "id": 52, "slug": "which-plants-survive-a-north-facing-balcony", "url": "/questions/which-plants-survive-a-north-facing-balcony", "web_url": "https://urnextdoor.com/questions/which-plants-survive-a-north-facing-balcony", "item": { "id": 52, "type": "question", "slug": "which-plants-survive-a-north-facing-balcony" }, "request_id": "9f8e7d6c5b4a3921" } }, "scheduled": { "summary": "Scheduled", "value": { "ok": true, "id": 52, "slug": "which-plants-survive-a-north-facing-balcony", "url": "/questions/which-plants-survive-a-north-facing-balcony", "web_url": "https://urnextdoor.com/questions/which-plants-survive-a-north-facing-balcony", "status": "scheduled", "scheduled_at": "2026-10-20T09:30:00Z", "item": { "id": 52, "type": "question", "slug": "which-plants-survive-a-north-facing-balcony" }, "request_id": "9f8e7d6c5b4a3921" } }, "withImage": { "summary": "Published with a featured image", "value": { "ok": true, "id": 52, "slug": "which-plants-survive-a-north-facing-balcony", "url": "/questions/which-plants-survive-a-north-facing-balcony", "web_url": "https://urnextdoor.com/questions/which-plants-survive-a-north-facing-balcony", "item": { "id": 52, "type": "question", "slug": "which-plants-survive-a-north-facing-balcony" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/polls": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Content" ], "summary": "Create a poll", "description": "Publishes a poll now, or schedules it. title and options (2 to 5 unique strings) are required. Counts against the poll quota.", "operationId": "createPoll", "x-required-scope": "content", "x-quota-action": "poll", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "basic": { "summary": "Publish now", "value": { "title": "When should the weekend cleanup start?", "options": [ "7 am", "8 am", "9 am" ], "tags": [ "neighbourhood" ] } }, "scheduled": { "summary": "Schedule for later", "value": { "title": "When should the weekend cleanup start?", "options": [ "7 am", "8 am", "9 am" ], "scheduled_at": "2026-10-20T09:30:00Z" } }, "withImage": { "summary": "With an uploaded image", "value": { "title": "When should the weekend cleanup start?", "options": [ "7 am", "8 am", "9 am" ], "featured_image": "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp" } } }, "schema": { "$ref": "#/components/schemas/CreatePollRequest" } } } }, "responses": { "201": { "description": "Created. Published now, or scheduled when scheduled_at was sent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Published now", "value": { "ok": true, "id": 18, "slug": "when-should-the-weekend-cleanup-start", "url": "/polls/when-should-the-weekend-cleanup-start", "web_url": "https://urnextdoor.com/polls/when-should-the-weekend-cleanup-start", "item": { "id": 18, "type": "poll", "slug": "when-should-the-weekend-cleanup-start" }, "request_id": "9f8e7d6c5b4a3921" } }, "scheduled": { "summary": "Scheduled", "value": { "ok": true, "id": 18, "slug": "when-should-the-weekend-cleanup-start", "url": "/polls/when-should-the-weekend-cleanup-start", "web_url": "https://urnextdoor.com/polls/when-should-the-weekend-cleanup-start", "status": "scheduled", "scheduled_at": "2026-10-20T09:30:00Z", "item": { "id": 18, "type": "poll", "slug": "when-should-the-weekend-cleanup-start" }, "request_id": "9f8e7d6c5b4a3921" } }, "withImage": { "summary": "Published with a featured image", "value": { "ok": true, "id": 18, "slug": "when-should-the-weekend-cleanup-start", "url": "/polls/when-should-the-weekend-cleanup-start", "web_url": "https://urnextdoor.com/polls/when-should-the-weekend-cleanup-start", "item": { "id": 18, "type": "poll", "slug": "when-should-the-weekend-cleanup-start" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/mcqs": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Content" ], "summary": "Create an MCQ", "description": "Publishes a multiple choice quiz question now, or schedules it. title, options (2 to 5) and correct_option_index (0-based) are required. Counts against the mcq quota.", "operationId": "createMcq", "x-required-scope": "content", "x-quota-action": "mcq", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "basic": { "summary": "Publish now", "value": { "title": "Which planet has the shortest year?", "options": [ "Venus", "Mercury", "Mars", "Earth" ], "correct_option_index": 1, "tags": [ "science" ] } }, "scheduled": { "summary": "Schedule for later", "value": { "title": "Which planet has the shortest year?", "options": [ "Venus", "Mercury", "Mars", "Earth" ], "correct_option_index": 1, "scheduled_at": "2026-10-20T09:30:00Z" } }, "withImage": { "summary": "With an uploaded image", "value": { "title": "Which planet has the shortest year?", "options": [ "Venus", "Mercury", "Mars", "Earth" ], "correct_option_index": 1, "featured_image": "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp" } } }, "schema": { "$ref": "#/components/schemas/CreateMcqRequest" } } } }, "responses": { "201": { "description": "Created. Published now, or scheduled when scheduled_at was sent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Published now", "value": { "ok": true, "id": 77, "slug": "which-planet-has-the-shortest-year", "url": "/mcqs/which-planet-has-the-shortest-year", "web_url": "https://urnextdoor.com/mcqs/which-planet-has-the-shortest-year", "item": { "id": 77, "type": "mcq", "slug": "which-planet-has-the-shortest-year" }, "request_id": "9f8e7d6c5b4a3921" } }, "scheduled": { "summary": "Scheduled", "value": { "ok": true, "id": 77, "slug": "which-planet-has-the-shortest-year", "url": "/mcqs/which-planet-has-the-shortest-year", "web_url": "https://urnextdoor.com/mcqs/which-planet-has-the-shortest-year", "status": "scheduled", "scheduled_at": "2026-10-20T09:30:00Z", "item": { "id": 77, "type": "mcq", "slug": "which-planet-has-the-shortest-year" }, "request_id": "9f8e7d6c5b4a3921" } }, "withImage": { "summary": "Published with a featured image", "value": { "ok": true, "id": 77, "slug": "which-planet-has-the-shortest-year", "url": "/mcqs/which-planet-has-the-shortest-year", "web_url": "https://urnextdoor.com/mcqs/which-planet-has-the-shortest-year", "item": { "id": 77, "type": "mcq", "slug": "which-planet-has-the-shortest-year" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/communities": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Content" ], "summary": "Create a community", "description": "Creates a community now (201), or schedules its creation (202) when scheduled_at is set. name must be unique. A scheduled creation fails later if the name is taken by then. Counts against the community quota.", "operationId": "createCommunity", "x-required-scope": "content", "x-quota-action": "community", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "basic": { "summary": "Create now", "value": { "name": "Morning Runners Pune", "description": "

Early runs, routes and race plans around Pune.

", "visibility": "public", "icon_url": "/avatars/community/running.png" } }, "scheduled": { "summary": "Create later", "value": { "name": "Morning Runners Pune", "description": "

Early runs, routes and race plans around Pune.

", "visibility": "ask_to_join", "scheduled_at": "2026-10-20T09:30:00Z" } } }, "schema": { "$ref": "#/components/schemas/CreateCommunityRequest" } } } }, "responses": { "201": { "description": "Created now.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Created now", "value": { "ok": true, "id": 5, "slug": "morning-runners-pune", "url": "/communities/morning-runners-pune", "web_url": "https://urnextdoor.com/communities/morning-runners-pune", "item": { "id": 5, "type": "community", "slug": "morning-runners-pune", "name": "Morning Runners Pune" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CreatedResponse" } } } }, "202": { "description": "Accepted: the community will be created at scheduled_at. id is the scheduled-creation id.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "scheduled": { "summary": "Scheduled", "value": { "ok": true, "status": "scheduled", "type": "community", "id": 5, "name": "Morning Runners Pune", "scheduled_at": "2026-10-20T09:30:00Z", "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/ScheduledCommunityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/services": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Content" ], "summary": "List a service", "description": "Publishes a Marketplace service now, or schedules it. title, body and category_id are required, plus a location (country_code, postal_code, state_id) unless service_mode is online. Prices are in rupees.", "operationId": "createService", "x-required-scope": "content", "x-quota-action": "service", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "basic": { "summary": "An online service with packages", "value": { "title": "Business website in 7 days", "body": "

I build fast, mobile friendly websites for small shops and clinics.

", "category_id": 12, "summary": "A fast, mobile friendly website for your shop or clinic.", "service_mode": "online", "packages": [ { "name": "Starter", "description": "One page site", "price": 4999, "delivery_days": 5, "revisions": 2, "features": [ "1 page", "Contact form" ] }, { "name": "Business", "description": "Up to 5 pages", "price": 14999, "delivery_days": 7, "revisions": -1, "features": [ "5 pages", "Blog", "Basic SEO" ] } ], "faqs": [ { "q": "Do you provide hosting?", "a": "I set it up on your account, so you own it." } ], "tags": [ "web-design" ] } }, "scheduled": { "summary": "An in person service, scheduled", "value": { "title": "Home tutoring for class 10 maths", "body": "

One to one sessions at your home, weekday evenings.

", "category_id": 31, "service_mode": "in_person", "country_code": "IN", "postal_code": "411001", "state_id": 19, "area": "Kothrud", "packages": [ { "name": "Monthly", "price": 6000, "delivery_days": 30, "features": [ "12 sessions" ] } ], "scheduled_at": "2026-10-20T09:30:00Z" } }, "withImage": { "summary": "With an uploaded image", "value": { "title": "Business website in 7 days", "body": "

I build fast, mobile friendly websites for small shops and clinics.

", "category_id": 12, "service_mode": "online", "packages": [ { "name": "Starter", "price": 4999, "delivery_days": 5 } ], "featured_image": "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp" } } }, "schema": { "$ref": "#/components/schemas/CreateServiceRequest" } } } }, "responses": { "201": { "description": "Created. Published now, or scheduled when scheduled_at was sent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Published now", "value": { "ok": true, "id": 9, "slug": "business-website-in-7-days", "url": "/marketplace/business-website-in-7-days", "web_url": "https://urnextdoor.com/marketplace/business-website-in-7-days", "item": { "id": 9, "type": "service", "slug": "business-website-in-7-days" }, "request_id": "9f8e7d6c5b4a3921" } }, "scheduled": { "summary": "Scheduled", "value": { "ok": true, "id": 9, "slug": "business-website-in-7-days", "url": "/marketplace/business-website-in-7-days", "web_url": "https://urnextdoor.com/marketplace/business-website-in-7-days", "status": "scheduled", "scheduled_at": "2026-10-20T09:30:00Z", "item": { "id": 9, "type": "service", "slug": "business-website-in-7-days" }, "request_id": "9f8e7d6c5b4a3921" } }, "withImage": { "summary": "Published with a featured image", "value": { "ok": true, "id": 9, "slug": "business-website-in-7-days", "url": "/marketplace/business-website-in-7-days", "web_url": "https://urnextdoor.com/marketplace/business-website-in-7-days", "item": { "id": 9, "type": "service", "slug": "business-website-in-7-days" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/jobs": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Content" ], "summary": "Post a job", "description": "Publishes a job now, or schedules it. title, body, employment_type, work_mode and experience_level are required (values from GET /job-options). Jobs take featured_image only, no gallery.", "operationId": "createJob", "x-required-scope": "content", "x-quota-action": "job", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "basic": { "summary": "A remote job", "value": { "title": "Backend developer (PHP)", "body": "

Join a small team building tools for local shops.

", "employment_type": "full_time", "work_mode": "remote", "experience_level": "mid", "openings": 2, "salary_min": 900000, "salary_max": 1400000, "salary_period": "yearly", "currency": "INR", "application_deadline": "2026-11-30", "summary": "Remote, full time, PHP and MySQL.", "tags": [ "php", "hiring" ] } }, "scheduled": { "summary": "An on site job, scheduled", "value": { "title": "Store manager", "body": "

Run our Kothrud store: staff, stock and customers.

", "employment_type": "full_time", "work_mode": "onsite", "experience_level": "senior", "country_code": "IN", "state_id": 19, "city_id": 1204, "salary_min": 35000, "salary_max": 45000, "salary_period": "monthly", "scheduled_at": "2026-10-20T09:30:00Z" } }, "withImage": { "summary": "With an uploaded image", "value": { "title": "Backend developer (PHP)", "body": "

Join a small team building tools for local shops.

", "employment_type": "full_time", "work_mode": "remote", "experience_level": "mid", "featured_image": "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp" } } }, "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } } }, "responses": { "201": { "description": "Created. Published now, or scheduled when scheduled_at was sent.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Published now", "value": { "ok": true, "id": 23, "slug": "backend-developer-php", "url": "/jobs/backend-developer-php", "web_url": "https://urnextdoor.com/jobs/backend-developer-php", "item": { "id": 23, "type": "job", "slug": "backend-developer-php" }, "request_id": "9f8e7d6c5b4a3921" } }, "scheduled": { "summary": "Scheduled", "value": { "ok": true, "id": 23, "slug": "backend-developer-php", "url": "/jobs/backend-developer-php", "web_url": "https://urnextdoor.com/jobs/backend-developer-php", "status": "scheduled", "scheduled_at": "2026-10-20T09:30:00Z", "item": { "id": 23, "type": "job", "slug": "backend-developer-php" }, "request_id": "9f8e7d6c5b4a3921" } }, "withImage": { "summary": "Published with a featured image", "value": { "ok": true, "id": 23, "slug": "backend-developer-php", "url": "/jobs/backend-developer-php", "web_url": "https://urnextdoor.com/jobs/backend-developer-php", "item": { "id": 23, "type": "job", "slug": "backend-developer-php" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/media": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Media" ], "summary": "Upload an image", "description": "Uploads one image as JSON (base64) or multipart. It is converted to WebP and must end at 2 MB or less. Use data.url as featured_image or in gallery. Counts against the media quota.", "operationId": "uploadMedia", "x-required-scope": "media", "x-quota-action": "media", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "base64": { "summary": "Base64 JSON (for AI generated images)", "value": { "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...", "filename": "cover.png", "context": "post" } } }, "schema": { "$ref": "#/components/schemas/MediaJsonRequest" } }, "multipart/form-data": { "examples": { "multipart": { "summary": "Multipart file upload", "value": { "file": "@cover.png", "context": "post" } } }, "schema": { "$ref": "#/components/schemas/MediaMultipartRequest" } } } }, "responses": { "201": { "description": "Stored.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "base64": { "summary": "Stored as WebP", "value": { "ok": true, "data": { "id": 318, "context": "post", "community_id": null, "url": "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp", "disk_path": "aarav/post/cover_3f9a1c2b7d4e_1792054800.webp", "original_name": "cover.png", "extension": "webp", "mime_type": "image/webp", "size_bytes": 184320, "created_at": "2026-10-15 09:00:00", "updated_at": "2026-10-15 09:00:00" }, "web_url": "https://urnextdoor.com/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp", "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/MediaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/scheduled": { "get": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Scheduling" ], "summary": "List scheduled items", "description": "Returns your pending scheduled items of every type, soonest first. Not quota-counted.", "operationId": "listScheduled", "x-required-scope": "schedule", "x-quota-action": null, "responses": { "200": { "description": "Your pending items.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Two pending items", "value": { "ok": true, "items": [ { "type": "post", "id": 41, "title": "Five easy ways to save water at home", "slug": "five-easy-ways-to-save-water-at-home", "url": "/posts/five-easy-ways-to-save-water-at-home", "edit_url": "/posts/five-easy-ways-to-save-water-at-home/edit", "scheduled_at": "2026-10-20T09:30:00Z", "created_at": "2026-10-15T09:00:00Z" }, { "type": "community", "id": 5, "title": "Morning Runners Pune", "slug": null, "url": null, "edit_url": null, "scheduled_at": "2026-10-21T04:00:00Z", "created_at": "2026-10-15T09:05:00Z" } ], "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/ScheduledListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "421": { "$ref": "#/components/responses/WrongHost" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/scheduled/{type}/{id}/reschedule": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Scheduling" ], "summary": "Reschedule an item", "description": "Moves a scheduled item to a new time (5 minutes to 180 days ahead, UTC). Answers the updated item. 409 if it is no longer scheduled. Not quota-counted.", "operationId": "rescheduleItem", "x-required-scope": "schedule", "x-quota-action": null, "parameters": [ { "$ref": "#/components/parameters/ScheduledTypePath" }, { "$ref": "#/components/parameters/ScheduledIdPath" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "basic": { "summary": "Move to a new time", "value": { "scheduled_at": "2026-10-22T06:00:00Z" } } }, "schema": { "$ref": "#/components/schemas/RescheduleRequest" } } } }, "responses": { "200": { "description": "The updated item.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Rescheduled", "value": { "ok": true, "item": { "type": "post", "id": 41, "title": "Five easy ways to save water at home", "slug": "five-easy-ways-to-save-water-at-home", "url": "/posts/five-easy-ways-to-save-water-at-home", "edit_url": "/posts/five-easy-ways-to-save-water-at-home/edit", "scheduled_at": "2026-10-22T06:00:00Z", "created_at": "2026-10-15T09:00:00Z" }, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/RescheduleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/scheduled/{type}/{id}/publish": { "post": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Scheduling" ], "summary": "Publish a scheduled item now", "description": "Publishes a scheduled item immediately instead of waiting. No body needed. 409 if it is no longer scheduled. Not quota-counted.", "operationId": "publishScheduledNow", "x-required-scope": "schedule", "x-quota-action": null, "parameters": [ { "$ref": "#/components/parameters/ScheduledTypePath" }, { "$ref": "#/components/parameters/ScheduledIdPath" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Published.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Published", "value": { "ok": true, "status": "published", "url": "/posts/five-easy-ways-to-save-water-at-home", "web_url": "https://urnextdoor.com/posts/five-easy-ways-to-save-water-at-home", "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/PublishNowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/scheduled/{type}/{id}": { "delete": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Scheduling" ], "summary": "Cancel a scheduled item", "description": "Cancels a scheduled item by deleting it, so it never goes live. This cannot be undone. Not quota-counted.", "operationId": "cancelScheduled", "x-required-scope": "schedule", "x-quota-action": null, "parameters": [ { "$ref": "#/components/parameters/ScheduledTypePath" }, { "$ref": "#/components/parameters/ScheduledIdPath" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cancelled.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Cancelled", "value": { "ok": true, "deleted": true, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CancelResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "421": { "$ref": "#/components/responses/WrongHost" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/communities/postable": { "get": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Lookups" ], "summary": "Communities you can post in", "description": "Lists the communities you may post into (you are an editor or above). Use id as community_id or slug as community on any create.", "operationId": "listPostableCommunities", "x-required-scope": "read", "x-quota-action": null, "responses": { "200": { "description": "Communities you can post in.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "basic": { "summary": "One community", "value": { "ok": true, "items": [ { "id": 5, "slug": "morning-runners-pune", "name": "Morning Runners Pune", "verified": null, "icon": "/avatars/community/running.png", "role": "creator" } ], "next_offset": 1, "has_more": false, "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/PostableCommunitiesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "421": { "$ref": "#/components/responses/WrongHost" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/service-categories": { "get": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Lookups" ], "summary": "Service categories", "description": "Returns the Marketplace category tree. Use a category id as category_id when you list a service.", "operationId": "listServiceCategories", "x-required-scope": "read", "x-quota-action": null, "responses": { "200": { "description": "The category tree.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Part of the tree", "value": { "ok": true, "categories": [ { "id": 3, "name": "Development", "slug": "development", "icon": null, "description": "Websites, apps and software.", "count": 42, "children": [ { "id": 12, "name": "Web development", "slug": "web-development", "count": 17 } ] } ], "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/ServiceCategoriesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "421": { "$ref": "#/components/responses/WrongHost" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/job-options": { "get": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Lookups" ], "summary": "Job options", "description": "Returns the allowed values for employment_type, work_mode, experience_level and salary_period on POST /jobs.", "operationId": "getJobOptions", "x-required-scope": "read", "x-quota-action": null, "responses": { "200": { "description": "Allowed values.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Allowed values", "value": { "ok": true, "employment_types": [ "full_time", "part_time", "contract", "internship", "temporary" ], "work_modes": [ "remote", "hybrid", "onsite" ], "experience_levels": [ "entry", "mid", "senior", "lead", "executive" ], "salary_periods": [ "yearly", "monthly", "hourly", "project" ], "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/JobOptionsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "421": { "$ref": "#/components/responses/WrongHost" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/geo": { "get": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Lookups" ], "summary": "Countries, states, districts and cities", "description": "Looks up places for service and job locations. level=countries (items have a code), level=states&country=IN, level=districts&state=19, or level=cities&state=19 (optionally &district=329).", "operationId": "getGeo", "x-required-scope": "read", "x-quota-action": null, "parameters": [ { "description": "Which list to return.", "name": "level", "in": "query", "required": true, "example": "states", "schema": { "type": "string", "enum": [ "countries", "states", "districts", "cities" ] } }, { "description": "ISO 3166-1 alpha-2 code. Needed for level=states.", "name": "country", "in": "query", "required": false, "example": "IN", "schema": { "type": "string" } }, { "description": "State id. Needed for level=districts and level=cities.", "name": "state", "in": "query", "required": false, "schema": { "type": "integer" } }, { "description": "District id. Narrows level=cities.", "name": "district", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Places at that level.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "basic": { "summary": "States of India (truncated)", "value": { "ok": true, "items": [ { "id": 19, "name": "Maharashtra", "slug": "maharashtra" }, { "id": 20, "name": "Manipur", "slug": "manipur" } ], "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/GeoResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "421": { "$ref": "#/components/responses/WrongHost" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } }, "/community-icons": { "get": { "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ "Lookups" ], "summary": "Community icons", "description": "Returns the built-in icons a community may use. Pass one as icon_url on POST /communities.", "operationId": "listCommunityIcons", "x-required-scope": "read", "x-quota-action": null, "responses": { "200": { "description": "Icon paths.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "basic": { "summary": "Icon paths (truncated)", "value": { "ok": true, "items": [ "/avatars/community/running.png", "/avatars/community/books.png" ], "request_id": "9f8e7d6c5b4a3921" } } }, "schema": { "$ref": "#/components/schemas/CommunityIconsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "421": { "$ref": "#/components/responses/WrongHost" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ApiDisabled" } } } } }, "components": { "parameters": { "IdempotencyKey": { "description": "Any unique string (a UUID is ideal), 1 to 64 characters of A-Z a-z 0-9 _ . : -. A repeat with the same key and body within 24 hours replays the first 2xx response instead of acting twice.", "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,64}$" } }, "ScheduledTypePath": { "description": "The item type.", "name": "type", "in": "path", "required": true, "example": "post", "schema": { "$ref": "#/components/schemas/ScheduledType" } }, "ScheduledIdPath": { "description": "The item id (for a community, the scheduled-creation id).", "name": "id", "in": "path", "required": true, "example": 41, "schema": { "type": "integer" } } }, "responses": { "ApiDisabled": { "description": "The API is switched off.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "api_disabled": { "value": { "ok": false, "error": "The API is switched off right now.", "code": "api_disabled", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "The body is not a JSON object, or the Idempotency-Key header is malformed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "invalid_json": { "value": { "ok": false, "error": "The body must be a JSON object.", "code": "invalid_json", "request_id": "a1b2c3d4e5f60718" } }, "invalid_idempotency_key": { "value": { "ok": false, "error": "Idempotency-Key must be 1 to 64 letters, digits or . _ : -", "code": "invalid_idempotency_key", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflicts with the current state, or the same Idempotency-Key is still being processed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "conflict": { "value": { "ok": false, "error": "This item is no longer scheduled.", "code": "conflict", "request_id": "a1b2c3d4e5f60718" } }, "idempotency_in_progress": { "value": { "ok": false, "error": "A request with this Idempotency-Key is still being processed. Retry shortly.", "code": "idempotency_in_progress", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks the scope, or the member may not do this.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "insufficient_scope": { "value": { "ok": false, "error": "This API key does not have the \"content\" scope. Create a key that includes it.", "code": "insufficient_scope", "request_id": "a1b2c3d4e5f60718" } }, "forbidden": { "value": { "ok": false, "error": "You are not an editor of that community.", "code": "forbidden", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Unknown route or item, or the item is not yours.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "not_found": { "value": { "ok": false, "error": "Not found.", "code": "not_found", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "The body is over the limit, or the image is over 8 MB.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "payload_too_large": { "value": { "ok": false, "error": "The request body is too large.", "code": "payload_too_large", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Our fault. Safe to retry with the same Idempotency-Key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "server_error": { "value": { "ok": false, "error": "Something went wrong on our side.", "code": "server_error", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Over 60 requests a minute from this member (or too many failed key checks from one address), or today's quota for this action is used up.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "examples": { "rate_limited": { "value": { "ok": false, "error": "Too many requests. Slow down and retry after a minute.", "code": "rate_limited", "request_id": "a1b2c3d4e5f60718" } }, "quota_exceeded": { "value": { "ok": false, "error": "You have used today's 20 posts for the API. The limit resets at 00:00 UTC.", "code": "quota_exceeded", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "No key, or the key is unknown, malformed, revoked or expired, or the member is not active.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "missing_api_key": { "value": { "ok": false, "error": "Send your API key as \"Authorization: Bearer und_sk_...\" or in an \"X-API-Key\" header.", "code": "missing_api_key", "request_id": "a1b2c3d4e5f60718" } }, "invalid_api_key": { "value": { "ok": false, "error": "This API key is not valid. It may be mistyped, revoked or expired, or the account is not active.", "code": "invalid_api_key", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnsupportedMediaType": { "description": "Wrong Content-Type, or a file type that is not allowed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "unsupported_media_type": { "value": { "ok": false, "error": "Send the body as JSON with Content-Type: application/json.", "code": "unsupported_media_type", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "Field errors, or an Idempotency-Key reused with a different body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "validation_failed": { "value": { "ok": false, "error": "title and body are required", "code": "validation_failed", "errors": { "body": "Body is required." }, "request_id": "a1b2c3d4e5f60718" } }, "idempotency_key_reused": { "value": { "ok": false, "error": "This Idempotency-Key was already used with a different request.", "code": "idempotency_key_reused", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } }, "WrongHost": { "description": "Called on a community subdomain. Use https://urnextdoor.com.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "examples": { "wrong_host": { "value": { "ok": false, "error": "Call the API on https://urnextdoor.com, not on a community address.", "code": "wrong_host", "request_id": "a1b2c3d4e5f60718" } } }, "schema": { "$ref": "#/components/schemas/Error" } } } } }, "headers": { "XRequestId": { "description": "A unique id for this request. Quote it when you contact support.", "schema": { "type": "string" } }, "CacheControl": { "description": "Always no-store.", "schema": { "type": "string", "const": "no-store" } }, "XRateLimitLimit": { "description": "Today's limit for the action this request counts against.", "schema": { "type": "integer" } }, "XRateLimitRemaining": { "description": "Requests of this action left today.", "schema": { "type": "integer" } }, "XRateLimitReset": { "description": "When the counter resets: unix seconds of the next UTC midnight.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } }, "IdempotentReplayed": { "description": "true when this is a stored response replayed for a repeated Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } } }, "schemas": { "Error": { "description": "Every error answers this envelope, whatever the Accept header.", "type": "object", "required": [ "ok", "error", "code", "request_id" ], "properties": { "ok": { "description": "Always false on an error.", "type": "boolean", "const": false }, "error": { "description": "A human readable message.", "type": "string" }, "code": { "description": "A stable machine code. See the Errors page.", "type": "string", "enum": [ "invalid_json", "invalid_idempotency_key", "missing_api_key", "invalid_api_key", "insufficient_scope", "forbidden", "not_found", "conflict", "idempotency_in_progress", "payload_too_large", "unsupported_media_type", "wrong_host", "validation_failed", "idempotency_key_reused", "rate_limited", "quota_exceeded", "server_error", "api_disabled" ] }, "errors": { "description": "Only on validation failures: one message per field name.", "type": "object", "additionalProperties": { "type": "string" } }, "request_id": { "description": "The same value as the X-Request-Id header. Quote it when you contact support.", "type": "string" } } }, "ImageUrl": { "description": "A /storage/... path returned by POST /media (data.url), or any https:// image URL (linked, not copied).", "type": "string", "examples": [ "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp" ] }, "ScheduledAt": { "description": "Publish later instead of now. ISO 8601 with an offset or Z, at least 5 minutes and at most 180 days ahead. Stored in UTC.", "type": "string", "format": "date-time", "examples": [ "2026-10-20T09:30:00Z" ] }, "User": { "type": "object", "required": [ "id", "username", "display_name", "plan", "profile_url" ], "properties": { "id": { "description": "Member id.", "type": "integer" }, "username": { "description": "Member handle.", "type": "string" }, "display_name": { "description": "Name shown on the site.", "type": "string" }, "plan": { "description": "The plan that sets your daily quotas.", "type": "string", "enum": [ "free", "pro", "business" ] }, "profile_url": { "description": "Public profile URL.", "type": "string", "format": "uri" } } }, "KeyInfo": { "type": "object", "required": [ "id", "name", "prefix", "scopes", "created_at", "expires_at" ], "properties": { "id": { "description": "Key id.", "type": "integer" }, "name": { "description": "The name you gave the key.", "type": "string" }, "prefix": { "description": "The first 12 characters of the key, safe to display.", "type": "string", "pattern": "^und_sk_[A-Za-z0-9]{5}$" }, "scopes": { "description": "What this key may do.", "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "description": "null when the key never expires.", "type": [ "string", "null" ], "format": "date-time" } } }, "Scope": { "type": "string", "enum": [ "content", "media", "schedule", "read" ] }, "MeResponse": { "type": "object", "required": [ "ok", "user", "key" ], "properties": { "ok": { "type": "boolean", "const": true }, "user": { "$ref": "#/components/schemas/User" }, "key": { "$ref": "#/components/schemas/KeyInfo" }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "QuotaUsage": { "type": "object", "required": [ "action", "limit", "used", "remaining" ], "properties": { "action": { "$ref": "#/components/schemas/QuotaAction" }, "limit": { "description": "Allowed per UTC day on your plan.", "type": "integer" }, "used": { "description": "Successful requests counted today.", "type": "integer" }, "remaining": { "description": "limit minus used.", "type": "integer" } } }, "QuotaAction": { "type": "string", "enum": [ "post", "question", "poll", "mcq", "community", "service", "job", "media" ] }, "UsageResponse": { "type": "object", "required": [ "ok", "plan", "day", "resets_at", "quotas" ], "properties": { "ok": { "type": "boolean", "const": true }, "plan": { "type": "string", "enum": [ "free", "pro", "business" ] }, "day": { "description": "The current UTC day.", "type": "string", "format": "date" }, "resets_at": { "description": "Next UTC midnight, when every counter resets.", "type": "string", "format": "date-time" }, "quotas": { "type": "array", "items": { "$ref": "#/components/schemas/QuotaUsage" } }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "CreatePostRequest": { "type": "object", "required": [ "title", "body" ], "properties": { "title": { "description": "The post title (plain text).", "type": "string" }, "body": { "description": "The post body as HTML. See the Formatting guide for allowed tags.", "type": "string" }, "tags": { "description": "Topic tags, without the leading #. Example: [\"water\", \"home\"].", "type": "array", "items": { "type": "string" } }, "community_id": { "description": "Post inside this community. Use an id from GET /communities/postable. You must be an editor (or above) of it.", "type": "integer" }, "community": { "description": "Alternative to community_id: the community slug. It is resolved to its id.", "type": "string" }, "featured_image": { "$ref": "#/components/schemas/ImageUrl" }, "gallery": { "description": "Extra images. Each is a /storage/... path from POST /media or an https:// image URL.", "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/ImageUrl" } }, "scheduled_at": { "$ref": "#/components/schemas/ScheduledAt" } } }, "CreateQuestionRequest": { "type": "object", "required": [ "title" ], "properties": { "title": { "description": "The question itself (plain text).", "type": "string" }, "body": { "description": "Optional details as HTML.", "type": "string" }, "tags": { "description": "Topic tags, without the leading #. Example: [\"water\", \"home\"].", "type": "array", "items": { "type": "string" } }, "community_id": { "description": "Post inside this community. Use an id from GET /communities/postable. You must be an editor (or above) of it.", "type": "integer" }, "community": { "description": "Alternative to community_id: the community slug. It is resolved to its id.", "type": "string" }, "featured_image": { "$ref": "#/components/schemas/ImageUrl" }, "gallery": { "description": "Extra images. Each is a /storage/... path from POST /media or an https:// image URL.", "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/ImageUrl" } }, "scheduled_at": { "$ref": "#/components/schemas/ScheduledAt" } } }, "CreatePollRequest": { "type": "object", "required": [ "title", "options" ], "properties": { "title": { "description": "The poll question (plain text).", "type": "string" }, "options": { "description": "The answers people vote on: 2 to 5 unique strings.", "type": "array", "minItems": 2, "maxItems": 5, "uniqueItems": true, "items": { "type": "string" } }, "body": { "description": "Optional context as HTML.", "type": "string" }, "tags": { "description": "Topic tags, without the leading #. Example: [\"water\", \"home\"].", "type": "array", "items": { "type": "string" } }, "community_id": { "description": "Post inside this community. Use an id from GET /communities/postable. You must be an editor (or above) of it.", "type": "integer" }, "community": { "description": "Alternative to community_id: the community slug. It is resolved to its id.", "type": "string" }, "featured_image": { "$ref": "#/components/schemas/ImageUrl" }, "gallery": { "description": "Extra images. Each is a /storage/... path from POST /media or an https:// image URL.", "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/ImageUrl" } }, "scheduled_at": { "$ref": "#/components/schemas/ScheduledAt" } } }, "CreateMcqRequest": { "type": "object", "required": [ "title", "options", "correct_option_index" ], "properties": { "title": { "description": "The quiz question (plain text).", "type": "string" }, "options": { "description": "The choices: 2 to 5 unique strings.", "type": "array", "minItems": 2, "maxItems": 5, "uniqueItems": true, "items": { "type": "string" } }, "correct_option_index": { "description": "The 0-based position of the correct choice in options.", "type": "integer", "minimum": 0, "maximum": 4 }, "body": { "description": "Optional context or explanation as HTML.", "type": "string" }, "tags": { "description": "Topic tags, without the leading #. Example: [\"water\", \"home\"].", "type": "array", "items": { "type": "string" } }, "community_id": { "description": "Post inside this community. Use an id from GET /communities/postable. You must be an editor (or above) of it.", "type": "integer" }, "community": { "description": "Alternative to community_id: the community slug. It is resolved to its id.", "type": "string" }, "featured_image": { "$ref": "#/components/schemas/ImageUrl" }, "gallery": { "description": "Extra images. Each is a /storage/... path from POST /media or an https:// image URL.", "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/ImageUrl" } }, "scheduled_at": { "$ref": "#/components/schemas/ScheduledAt" } } }, "CreateCommunityRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The community name. It must be unique.", "type": "string" }, "description": { "description": "What the community is about, as HTML.", "type": "string" }, "visibility": { "description": "Who can see and join it.", "type": "string", "enum": [ "public", "ask_to_join", "private" ] }, "icon_url": { "description": "One of the paths returned by GET /community-icons.", "type": "string" }, "scheduled_at": { "$ref": "#/components/schemas/ScheduledAt" } } }, "ServicePackage": { "type": "object", "required": [ "price" ], "properties": { "name": { "description": "Package name. Defaults to Basic, Standard or Premium by position.", "type": "string", "maxLength": 120 }, "description": { "description": "What the package includes.", "type": "string", "maxLength": 500 }, "price": { "description": "Price in Indian rupees, for example 4999. A package without a positive price is skipped.", "type": "number", "exclusiveMinimum": 0 }, "delivery_days": { "description": "Days to deliver. Defaults to 1.", "type": "integer", "minimum": 1 }, "revisions": { "description": "Revisions included. -1 means unlimited.", "type": "integer", "minimum": -1 }, "features": { "description": "Short feature lines, up to 20.", "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 200 } } } }, "ServiceFaq": { "type": "object", "required": [ "q", "a" ], "properties": { "q": { "description": "The question.", "type": "string", "maxLength": 200 }, "a": { "description": "The answer.", "type": "string", "maxLength": 1000 } } }, "CreateServiceRequest": { "type": "object", "required": [ "title", "body", "category_id" ], "properties": { "title": { "description": "The service title (plain text).", "type": "string" }, "body": { "description": "The full description as HTML.", "type": "string" }, "category_id": { "description": "A category id from GET /service-categories.", "type": "integer" }, "summary": { "description": "A short plain text summary shown on cards.", "type": "string", "maxLength": 300 }, "service_mode": { "description": "How you deliver. Unless it is online, a location is required.", "type": "string", "enum": [ "online", "in_person", "both" ], "default": "both" }, "country_code": { "description": "ISO 3166-1 alpha-2 country, for example IN. Required unless service_mode is online.", "type": "string" }, "postal_code": { "description": "Postal code, valid for the country. Required unless service_mode is online.", "type": "string" }, "state_id": { "description": "From GET /geo?level=states. At least a state (or a district or city) is required unless service_mode is online.", "type": "integer" }, "district_id": { "description": "From GET /geo?level=districts. If you send a district, also send a city.", "type": "integer" }, "city_id": { "description": "From GET /geo?level=cities.", "type": "integer" }, "area": { "description": "Neighbourhood or area, free text.", "type": "string", "maxLength": 120 }, "packages": { "description": "Up to 3 priced packages.", "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/ServicePackage" } }, "faqs": { "description": "Up to 20 questions and answers.", "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ServiceFaq" } }, "tags": { "description": "Topic tags, without the leading #. Example: [\"water\", \"home\"].", "type": "array", "items": { "type": "string" } }, "community_id": { "description": "Post inside this community. Use an id from GET /communities/postable. You must be an editor (or above) of it.", "type": "integer" }, "community": { "description": "Alternative to community_id: the community slug. It is resolved to its id.", "type": "string" }, "featured_image": { "$ref": "#/components/schemas/ImageUrl" }, "gallery": { "description": "Extra images. Each is a /storage/... path from POST /media or an https:// image URL.", "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/ImageUrl" } }, "scheduled_at": { "$ref": "#/components/schemas/ScheduledAt" } } }, "CreateJobRequest": { "type": "object", "required": [ "title", "body", "employment_type", "work_mode", "experience_level" ], "properties": { "title": { "description": "The job title (plain text).", "type": "string" }, "body": { "description": "The job description as HTML.", "type": "string" }, "employment_type": { "description": "One of employment_types from GET /job-options, for example full_time.", "type": "string" }, "work_mode": { "description": "One of work_modes from GET /job-options, for example remote. Location fields are ignored when it is remote.", "type": "string" }, "experience_level": { "description": "One of experience_levels from GET /job-options, for example mid.", "type": "string" }, "openings": { "description": "Number of openings.", "type": "integer", "minimum": 1, "maximum": 999 }, "salary_min": { "description": "Lowest salary in currency, per salary_period.", "type": "number" }, "salary_max": { "description": "Highest salary in currency, per salary_period.", "type": "number" }, "salary_period": { "description": "One of salary_periods from GET /job-options, for example yearly.", "type": "string" }, "currency": { "description": "Three letter currency code.", "type": "string", "pattern": "^[A-Z]{3}$", "default": "INR" }, "application_deadline": { "description": "Last day to apply, YYYY-MM-DD.", "type": "string", "format": "date" }, "summary": { "description": "A short plain text summary shown on cards.", "type": "string", "maxLength": 300 }, "country_code": { "description": "ISO 3166-1 alpha-2 country. Ignored when work_mode is remote.", "type": "string" }, "state_id": { "description": "From GET /geo. Ignored when work_mode is remote.", "type": "integer" }, "district_id": { "description": "From GET /geo. Ignored when work_mode is remote.", "type": "integer" }, "city_id": { "description": "From GET /geo. Ignored when work_mode is remote.", "type": "integer" }, "area": { "description": "Neighbourhood or area, free text. Ignored when work_mode is remote.", "type": "string" }, "featured_image": { "$ref": "#/components/schemas/ImageUrl" }, "tags": { "description": "Topic tags, without the leading #. Example: [\"water\", \"home\"].", "type": "array", "items": { "type": "string" } }, "community_id": { "description": "Post inside this community. Use an id from GET /communities/postable. You must be an editor (or above) of it.", "type": "integer" }, "community": { "description": "Alternative to community_id: the community slug. It is resolved to its id.", "type": "string" }, "scheduled_at": { "$ref": "#/components/schemas/ScheduledAt" } } }, "CreatedResponse": { "type": "object", "required": [ "ok", "id", "url", "web_url" ], "properties": { "ok": { "type": "boolean", "const": true }, "id": { "description": "The new item id.", "type": "integer" }, "slug": { "description": "The URL slug.", "type": "string" }, "url": { "description": "Root-relative URL of the item.", "type": "string" }, "web_url": { "description": "Full URL to open or share.", "type": "string", "format": "uri" }, "status": { "description": "Present only when scheduled_at was sent.", "type": "string", "enum": [ "scheduled" ] }, "scheduled_at": { "description": "Present only when scheduled: when it goes live, in UTC.", "type": "string", "format": "date-time" }, "item": { "description": "The card the website and app show for this item. Its fields may grow over time.", "type": "object", "additionalProperties": true }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "ScheduledCommunityResponse": { "type": "object", "required": [ "ok", "status", "type", "id", "scheduled_at" ], "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "string", "const": "scheduled" }, "type": { "type": "string", "const": "community" }, "id": { "description": "The scheduled-creation id. Use it with the /scheduled endpoints.", "type": "integer" }, "name": { "description": "The community name that will be created.", "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "MediaJsonRequest": { "type": "object", "required": [ "image_base64" ], "properties": { "image_base64": { "description": "The image as raw base64 or a data: URI (data:image/png;base64,...). PNG, JPEG, GIF or WebP, up to 8 MB before conversion.", "type": "string" }, "filename": { "description": "A file name such as cover.png. Used to name the stored file.", "type": "string" }, "context": { "$ref": "#/components/schemas/MediaContext" }, "community": { "description": "Optional community slug to file the image under.", "type": "string" } } }, "MediaMultipartRequest": { "type": "object", "required": [ "file" ], "properties": { "file": { "description": "The image file.", "type": "string", "contentMediaType": "application/octet-stream" }, "context": { "$ref": "#/components/schemas/MediaContext" }, "community": { "description": "Optional community slug to file the image under.", "type": "string" } } }, "MediaContext": { "description": "What the image is for.", "type": "string", "enum": [ "post", "question", "poll", "mcq", "community", "service", "job", "misc" ], "default": "post" }, "Media": { "type": "object", "required": [ "id", "url" ], "properties": { "id": { "type": "integer" }, "context": { "$ref": "#/components/schemas/MediaContext" }, "community_id": { "type": [ "integer", "null" ] }, "url": { "description": "Root-relative /storage/... path. Use it as featured_image or in gallery.", "type": "string" }, "disk_path": { "type": "string" }, "original_name": { "type": "string" }, "extension": { "description": "webp after conversion.", "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "MediaResponse": { "type": "object", "required": [ "ok", "data", "web_url" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Media" }, "web_url": { "description": "Full URL of the stored image.", "type": "string", "format": "uri" }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "ScheduledType": { "description": "In paths, job and job_post both mean a job. Lists report jobs as job_post.", "type": "string", "enum": [ "post", "question", "poll", "mcq", "service", "job", "job_post", "community" ] }, "ScheduledItem": { "type": "object", "required": [ "type", "id", "scheduled_at" ], "properties": { "type": { "$ref": "#/components/schemas/ScheduledType" }, "id": { "description": "For a community this is the scheduled-creation id.", "type": "integer" }, "title": { "description": "The title, or the name of a community.", "type": "string" }, "slug": { "description": "Empty for a community that is not created yet.", "type": "string" }, "url": { "description": "Root-relative URL. null for a community that is not created yet.", "type": [ "string", "null" ] }, "edit_url": { "description": "Where to edit it on the website. null for a community that is not created yet.", "type": [ "string", "null" ] }, "scheduled_at": { "description": "When it goes live, in UTC.", "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ScheduledListResponse": { "type": "object", "required": [ "ok", "items" ], "properties": { "ok": { "type": "boolean", "const": true }, "items": { "description": "Pending items, soonest first.", "type": "array", "items": { "$ref": "#/components/schemas/ScheduledItem" } }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "RescheduleRequest": { "type": "object", "required": [ "scheduled_at" ], "properties": { "scheduled_at": { "$ref": "#/components/schemas/ScheduledAt" } } }, "RescheduleResponse": { "type": "object", "required": [ "ok", "item" ], "properties": { "ok": { "type": "boolean", "const": true }, "item": { "$ref": "#/components/schemas/ScheduledItem" }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "PublishNowResponse": { "type": "object", "required": [ "ok", "status", "url" ], "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "string", "const": "published" }, "id": { "description": "Only for a community: the id of the community just created.", "type": "integer" }, "slug": { "description": "Only for a community: its slug.", "type": "string" }, "url": { "description": "Root-relative URL where the item now lives.", "type": "string" }, "web_url": { "description": "Full URL to open or share.", "type": "string", "format": "uri" }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "CancelResponse": { "type": "object", "required": [ "ok", "deleted" ], "properties": { "ok": { "type": "boolean", "const": true }, "deleted": { "type": "boolean", "const": true }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "PostableCommunity": { "type": "object", "required": [ "id", "slug", "name", "role" ], "properties": { "id": { "description": "Use as community_id.", "type": "integer" }, "slug": { "description": "Use as community.", "type": "string" }, "name": { "type": "string" }, "verified": { "description": "The community verified badge, or null.", "type": [ "string", "null" ] }, "icon": { "description": "Icon path, or null.", "type": [ "string", "null" ] }, "role": { "description": "Your role. Editors and above may post.", "type": "string", "enum": [ "editor", "admin", "creator" ] } } }, "PostableCommunitiesResponse": { "type": "object", "required": [ "ok", "items" ], "properties": { "ok": { "type": "boolean", "const": true }, "items": { "description": "Up to 200 communities, by name.", "type": "array", "items": { "$ref": "#/components/schemas/PostableCommunity" } }, "next_offset": { "type": "integer" }, "has_more": { "type": "boolean" }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "ServiceSubcategory": { "type": "object", "required": [ "id", "name", "slug" ], "properties": { "id": { "description": "Use as category_id.", "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "count": { "description": "Published services in it.", "type": "integer" } } }, "ServiceCategory": { "type": "object", "required": [ "id", "name", "slug", "children" ], "properties": { "id": { "description": "A top level group. Prefer a child id as category_id.", "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "count": { "description": "Published services in the group and its children.", "type": "integer" }, "children": { "description": "The categories inside this group.", "type": "array", "items": { "$ref": "#/components/schemas/ServiceSubcategory" } } } }, "ServiceCategoriesResponse": { "type": "object", "required": [ "ok", "categories" ], "properties": { "ok": { "type": "boolean", "const": true }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceCategory" } }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "JobOptionsResponse": { "type": "object", "required": [ "ok", "employment_types", "work_modes", "experience_levels", "salary_periods" ], "properties": { "ok": { "type": "boolean", "const": true }, "employment_types": { "description": "Allowed employment_type values.", "type": "array", "items": { "type": "string" } }, "work_modes": { "description": "Allowed work_mode values.", "type": "array", "items": { "type": "string" } }, "experience_levels": { "description": "Allowed experience_level values.", "type": "array", "items": { "type": "string" } }, "salary_periods": { "description": "Allowed salary_period values.", "type": "array", "items": { "type": "string" } }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "GeoPlace": { "type": "object", "properties": { "id": { "description": "States, districts and cities: use as state_id, district_id or city_id.", "type": "integer" }, "code": { "description": "Countries only: the ISO code to use as country_code.", "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "district_id": { "description": "Cities only.", "type": [ "integer", "null" ] }, "postal_regex": { "description": "Countries only: the postal code pattern, when known.", "type": [ "string", "null" ] } }, "additionalProperties": true }, "GeoResponse": { "type": "object", "required": [ "ok", "items" ], "properties": { "ok": { "type": "boolean", "const": true }, "items": { "description": "Places at the requested level.", "type": "array", "items": { "$ref": "#/components/schemas/GeoPlace" } }, "default": { "type": "string", "description": "Countries only: the suggested default country code." }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } }, "CommunityIconsResponse": { "type": "object", "required": [ "ok", "items" ], "properties": { "ok": { "type": "boolean", "const": true }, "items": { "description": "Paths such as /avatars/... Use one as icon_url.", "type": "array", "items": { "type": "string" } }, "request_id": { "description": "The same value as the X-Request-Id header.", "type": "string" } } } }, "securitySchemes": { "bearerAuth": { "description": "Authorization: Bearer und_sk_... Your personal API key from Settings > API keys (und_sk_ followed by 49 letters and digits).", "type": "http", "scheme": "bearer" }, "apiKeyHeader": { "description": "The same key in an X-API-Key header, for tools that cannot set Authorization.", "name": "X-API-Key", "in": "header", "type": "apiKey" } } } }