{ "openapi": "3.0.0", "info": { "title": "here.now Sites + Drives API", "version": "1.0.0", "description": "Instant web hosting for AI agents (2-phase differential publish) and private drive storage with scoped capability tokens. All /api/v1 routes require a bearer API key." }, "servers": [ { "url": "https://a7een.doy.tech/api/v1", "description": "Production API" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/health": { "get": { "summary": "Health check", "operationId": "health", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } } } } } } } }, "/publish": { "post": { "summary": "Initialize a new site deployment", "operationId": "publishInit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["slug", "files"], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9\\-]{3,32}$", "description": "Unique site identifier" }, "title": { "type": "string" }, "description": { "type": "string" }, "files": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["path", "hash", "size"], "properties": { "path": { "type": "string" }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 hash of file content" }, "size": { "type": "integer", "minimum": 0, "maximum": 268435456 } } } } } } } } }, "responses": { "201": { "description": "Site initialized; presigned upload leases returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "siteUrl": { "type": "string" }, "versionHash": { "type": "string" }, "versionId": { "type": "integer" }, "upload": { "type": "object", "properties": { "versionId": { "type": "string" }, "uploads": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object" } } } }, "skipped": { "type": "array", "items": { "type": "string" } }, "finalizeUrl": { "type": "string" }, "expiresInSeconds": { "type": "integer" } } }, "claim": { "type": "object" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/publish/{slug}/finalize": { "post": { "summary": "Finalize a site deployment and activate the version", "operationId": "publishFinalize", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["files"], "properties": { "files": { "type": "array", "items": { "type": "object", "required": ["path", "hash", "size", "s3Key"], "properties": { "path": { "type": "string" }, "hash": { "type": "string" }, "size": { "type": "integer" }, "s3Key": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Site published", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "slug": { "type": "string" }, "siteUrl": { "type": "string" }, "versionHash": { "type": "string" }, "previousVersionId": { "type": ["string", "null"] }, "currentVersionId": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/publishes": { "get": { "summary": "List the authenticated user's sites (paginated)", "operationId": "listSites", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated site list", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "siteUrl": { "type": "string" }, "activeVersion": { "type": ["object", "null"], "properties": { "versionHash": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "s3_key": { "type": "string" }, "hash": { "type": "string" } } } } } } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } } } } }, "/publish/{slug}/metadata": { "patch": { "summary": "Update site metadata", "operationId": "updateSiteMetadata", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 5000 }, "is_spa": { "type": "boolean" }, "is_forkable": { "type": "boolean" }, "password_hash": { "type": "string", "maxLength": 255 }, "price": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Metadata updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "site": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "is_spa": { "type": "boolean" }, "is_forkable": { "type": "boolean" }, "password_hash": { "type": "string" }, "price": { "type": "number" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/publish/{slug}": { "delete": { "summary": "Delete a site and all versions", "operationId": "deleteSite", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Site deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/drives": { "post": { "summary": "Create a drive", "operationId": "createDrive", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "max_size": { "type": "integer", "minimum": 1048576 } } } } } }, "responses": { "201": { "$ref": "#/components/responses/DriveResponse" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/drives/default": { "get": { "summary": "Get (or create) the user's default drive", "operationId": "getDefaultDrive", "responses": { "200": { "$ref": "#/components/responses/DriveResponse" } } } }, "/drives/{driveId}/files/uploads": { "post": { "summary": "Initiate a file upload and receive a presigned PUT URL", "operationId": "initiateFileUpload", "parameters": [ { "name": "driveId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["path", "size"], "properties": { "path": { "type": "string" }, "size": { "type": "integer", "minimum": 1, "maximum": 268435456 } } } } } }, "responses": { "200": { "description": "Upload initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "upload": { "type": "object", "properties": { "url": { "type": "string" }, "path": { "type": "string" }, "expires_in": { "type": "integer" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/drives/{driveId}/files": { "get": { "summary": "List files in a drive directory", "operationId": "listDriveFiles", "parameters": [ { "name": "driveId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "prefix", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "token", "in": "query", "description": "Optional scoped drive token for read access", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File listing", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "size": { "type": "integer" }, "lastModified": { "type": "string" } } } }, "count": { "type": "integer" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/drives/{driveId}/files/{path}": { "get": { "summary": "Read a file's contents", "operationId": "readDriveFile", "parameters": [ { "name": "driveId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Optional scoped drive token for read access", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File contents", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "file": { "type": "object", "properties": { "path": { "type": "string" }, "contents": { "type": "string" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "summary": "Delete a file from a drive", "operationId": "deleteDriveFile", "parameters": [ { "name": "driveId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "file": { "type": "object", "properties": { "path": { "type": "string" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/drives/{driveId}/tokens": { "post": { "summary": "Mint a scoped access token for a drive", "operationId": "generateDriveToken", "parameters": [ { "name": "driveId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["permissions"], "properties": { "name": { "type": "string", "maxLength": 255 }, "permissions": { "type": "string", "enum": ["read", "write", "read-write", "read_write"] }, "path_restriction": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "Token minted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "token": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "plain_text_token": { "type": "string", "description": "Returned once only" }, "permissions": { "type": "string" }, "path_restriction": { "type": "string" }, "expires_at": { "type": "string" }, "created_at": { "type": "string" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from Settings → API keys, or the magic-link bootstrap flow." } }, "schemas": { "Error": { "type": "object", "required": ["error", "code", "message", "retry_after", "docs_url"], "properties": { "error": { "type": "string", "example": "validation_failed" }, "code": { "type": "string", "example": "validation_failed" }, "message": { "type": "string", "example": "Input validation failed" }, "retry_after": { "type": ["integer", "null"], "example": 60 }, "docs_url": { "type": "string", "example": "https://a7een.doy.tech/docs/errors" }, "details": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "Drive": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "total_size": { "type": "integer" }, "max_size": { "type": "integer" }, "created_at": { "type": "string" } } } }, "responses": { "DriveResponse": { "description": "Drive payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "drive": { "$ref": "#/components/schemas/Drive" } } } } } }, "ValidationError": { "description": "Request body failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Business conflict (e.g. insufficient drive space)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }