{ "openapi": "3.1.0", "info": { "title": "AfterPencil API", "version": "1.0.0", "summary": "Projects of AfterPencil, the floor plan editor, for agents and integrations.", "description": "Read and save AfterPencil projects from an agent or an integration (n8n, scripts). Sign in with OAuth 2.1 (authorization code with PKCE and dynamic client registration), or use an API key the person creates in the editor (Integrations); either way you reach the projects of one workspace, with view or view and edit access. Agents and API keys need a workspace on Plus or Pro: on Free the API answers 403 with `code: plan_required`. A project is a snapshot of the plan with a `version`: to save, send the version you read; if someone saved in between, the API answers 409 with the current version. The plan format is described in https://app.afterpencil.com/agents/model.md; to edit with commands instead of raw JSON, use the MCP server at https://mcp.afterpencil.com/mcp. Units are meters.", "contact": { "url": "https://app.afterpencil.com/llms.txt" } }, "servers": [ { "url": "https://api.afterpencil.com" } ], "tags": [ { "name": "OAuth", "description": "Authorization server for agents and integrations." }, { "name": "Projects", "description": "Projects of the connected workspace." } ], "security": [ { "oauth2": [ "projects:read" ] }, { "apiKey": [] } ], "paths": { "/.well-known/oauth-authorization-server": { "get": { "tags": [ "OAuth" ], "operationId": "getAuthorizationServerMetadata", "summary": "Authorization server metadata (RFC 8414)", "security": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "description": "Endpoints, scopes and supported methods" } } } }, "/oauth/register": { "post": { "tags": [ "OAuth" ], "operationId": "registerClient", "summary": "Register a public client (RFC 7591)", "security": [], "description": "Public clients only (`token_endpoint_auth_method: none`), with PKCE. Redirect URIs: https, http on localhost, or an app scheme.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRegistration" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } }, "description": "The client, without a secret" }, "400": { "$ref": "#/components/responses/OAuthError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/oauth/authorize": { "get": { "tags": [ "OAuth" ], "operationId": "authorize", "summary": "Start an authorization", "security": [], "description": "Open in the person's browser. Redirects to the consent page of the editor, and from there back to `redirect_uri` with `code` and `state`, or `error=access_denied`.", "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "const": "code" } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" }, "description": "BASE64URL(SHA256(code_verifier))" }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "const": "S256" } }, { "name": "scope", "in": "query", "schema": { "type": "string", "examples": [ "projects:read projects:write" ] }, "description": "Space separated; without it, both. The person decides whether you may edit." }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "resource", "in": "query", "schema": { "type": "string", "format": "uri" }, "description": "RFC 8707: the API or the MCP server" } ], "responses": { "302": { "description": "To the consent page, or back to the client with an error" }, "400": { "$ref": "#/components/responses/OAuthError" } } } }, "/oauth/token": { "post": { "tags": [ "OAuth" ], "operationId": "token", "summary": "Exchange a code or a refresh token", "security": [], "description": "Access tokens are short; refresh tokens rotate: each use returns a new one and the old one stops working.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthorizationCodeGrant" }, { "$ref": "#/components/schemas/RefreshTokenGrant" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/OAuthError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/oauth/revoke": { "post": { "tags": [ "OAuth" ], "operationId": "revoke", "summary": "Revoke a token (RFC 7009)", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token", "client_id" ], "properties": { "token": { "type": "string" }, "client_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Revoked, or it did not exist" } } } }, "/v1/agent": { "get": { "tags": [ "Projects" ], "operationId": "getAgent", "summary": "This connection", "description": "The client, the workspace and what it may do today: the least of what was granted and the person's current role.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/projects": { "get": { "tags": [ "Projects" ], "operationId": "listProjects", "summary": "List projects", "description": "Projects of the connected workspace, most recently saved first, without their plans.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSummary" } } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthenticated" } } }, "post": { "tags": [ "Projects" ], "operationId": "createProject", "summary": "Create a project", "security": [ { "oauth2": [ "projects:write" ] }, { "apiKey": [] } ], "description": "In the connected workspace. Needs `projects:write` and a person who can edit there.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "plan" ], "properties": { "name": { "type": "string", "maxLength": 160 }, "plan": { "$ref": "#/components/schemas/Plan" } } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/projects/{project}": { "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id" } ], "get": { "tags": [ "Projects" ], "operationId": "getProject", "summary": "Get a project with its plan", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Projects" ], "operationId": "saveProject", "summary": "Save a project", "security": [ { "oauth2": [ "projects:write" ] }, { "apiKey": [] } ], "description": "Send the `version` you read, and the name, the plan or both. If someone saved in between, 409 with the current version.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveProject" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "patch": { "tags": [ "Projects" ], "operationId": "patchProject", "summary": "Save a project (same as PUT)", "security": [ { "oauth2": [ "projects:write" ] }, { "apiKey": [] } ], "description": "Send the `version` you read, and the name, the plan or both. If someone saved in between, 409 with the current version.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveProject" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Projects" ], "operationId": "deleteProject", "summary": "Delete a project", "description": "Only the owner of the workspace, from the editor: a connection gets 403.", "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "Authorization code with PKCE (S256); public clients register at /oauth/register.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.afterpencil.com/oauth/authorize", "tokenUrl": "https://api.afterpencil.com/oauth/token", "refreshUrl": "https://api.afterpencil.com/oauth/token", "scopes": { "projects:read": "View the projects of the chosen workspace", "projects:write": "Also change and create projects" } } } }, "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key created in the editor (Integrations), sent as `Authorization: Bearer `. It does not expire; the person revokes it from their account." } }, "schemas": { "ProjectSummary": { "type": "object", "required": [ "id", "name", "workspace_id", "version", "shared", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "workspace_id": { "type": "integer" }, "version": { "type": "integer", "minimum": 1, "description": "Goes up with every save" }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "editor", "viewer", null ], "description": "The person's role in the workspace" }, "shared": { "type": "boolean", "description": "Whether it has a read-only link" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Project": { "allOf": [ { "$ref": "#/components/schemas/ProjectSummary" }, { "type": "object", "required": [ "plan" ], "properties": { "plan": { "$ref": "#/components/schemas/Plan" } } } ] }, "Plan": { "type": "object", "required": [ "levels", "walls" ], "additionalProperties": true, "description": "The plan snapshot: collections keyed by id (levels, nodes, walls, openings, furniture…) with `schemaVersion`. Empty collections are `{}`. See https://app.afterpencil.com/agents/model.md.", "properties": { "schemaVersion": { "type": "integer" }, "levels": { "type": "object" }, "nodes": { "type": "object" }, "walls": { "type": "object" } } }, "SaveProject": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1, "description": "The version you read" }, "name": { "type": "string", "maxLength": 160 }, "plan": { "$ref": "#/components/schemas/Plan" } } }, "Agent": { "type": "object", "required": [ "client", "workspace", "access", "scopes", "plan" ], "properties": { "client": { "type": "string" }, "workspace": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "access": { "type": "string", "enum": [ "read", "write", "none" ], "description": "What the connection may do today: the least of what was granted, the person's role and the plan (`none` when the plan does not include agents)" }, "scopes": { "type": "array", "items": { "type": "string" } }, "plan": { "type": "string", "enum": [ "free", "plus", "pro" ], "description": "The workspace plan" } } }, "ClientRegistration": { "type": "object", "required": [ "redirect_uris" ], "properties": { "client_name": { "type": "string", "maxLength": 100 }, "redirect_uris": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uri" } }, "token_endpoint_auth_method": { "const": "none" } } }, "Client": { "type": "object", "required": [ "client_id", "client_name", "redirect_uris" ], "properties": { "client_id": { "type": "string" }, "client_id_issued_at": { "type": "integer" }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "const": "none" } } }, "AuthorizationCodeGrant": { "type": "object", "required": [ "grant_type", "client_id", "code", "redirect_uri", "code_verifier" ], "properties": { "grant_type": { "const": "authorization_code" }, "client_id": { "type": "string" }, "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "code_verifier": { "type": "string" }, "resource": { "type": "string" } } }, "RefreshTokenGrant": { "type": "object", "required": [ "grant_type", "client_id", "refresh_token" ], "properties": { "grant_type": { "const": "refresh_token" }, "client_id": { "type": "string" }, "refresh_token": { "type": "string" } } }, "TokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "refresh_token", "scope" ], "properties": { "access_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "expires_in": { "type": "integer", "description": "Seconds" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } } }, "Message": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } }, "responses": { "Unauthenticated": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "Missing, expired or revoked token" }, "Forbidden": { "description": "The connection cannot do that: it only views, the project is in another workspace, only the editor can, or the workspace plan does not include agents (`code: plan_required`)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "plan_required" ] } } } } } }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "Not found" }, "TooManyRequests": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "Too many requests" }, "ValidationError": { "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } }, "description": "Invalid request" }, "Conflict": { "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "version" ], "properties": { "message": { "type": "string" }, "version": { "type": "integer", "description": "The current version" } } } } }, "description": "Someone saved in between: read the project again and redo the change" }, "OAuthError": { "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "examples": [ "invalid_grant", "invalid_request", "invalid_redirect_uri" ] }, "error_description": { "type": "string" } } } } }, "description": "OAuth error (RFC 6749)" } } } }