feat(docs): add POST /api/upload endpoint reference #196
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,163 @@ | ||
| { | ||
| "openapi": "3.1.0", | ||
| "info": { | ||
| "title": "Recoup API - Upload", | ||
| "description": "API documentation for the Recoup platform - an AI agent platform for the music industry", | ||
| "license": { | ||
| "name": "MIT" | ||
| }, | ||
| "version": "1.0.0" | ||
| }, | ||
| "security": [ | ||
| { "apiKeyAuth": [] }, | ||
| { "bearerAuth": [] } | ||
| ], | ||
| "paths": { | ||
| "/api/upload": { | ||
| "post": { | ||
| "description": "Uploads a file and returns a permanent CDN-fronted HTTPS URL. Accepts a single file via multipart/form-data under the field name `file`. The caller's accountId is stamped onto the storage object's metadata as `uploaded_by` for audit purposes.", | ||
| "requestBody": { | ||
| "required": true, | ||
| "content": { | ||
| "multipart/form-data": { | ||
| "schema": { | ||
| "type": "object", | ||
| "required": ["file"], | ||
| "properties": { | ||
| "file": { | ||
| "type": "string", | ||
| "format": "binary", | ||
| "description": "The file bytes to upload. The file's Content-Type must be on the server allowlist (image/*, application/pdf, text/csv, text/markdown, text/plain, application/json, audio/mpeg, audio/wav, audio/x-m4a, audio/webm). Typeless / octet-stream uploads are rejected." | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "description": "File uploaded successfully", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/UploadResponse" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "400": { | ||
| "description": "Bad request — multipart body could not be parsed or no `file` field was provided.", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/UploadErrorResponse" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "401": { | ||
| "description": "Missing or invalid authentication. Provide either an `Authorization: Bearer <token>` header or `x-api-key`.", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/UploadErrorResponse" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "415": { | ||
| "description": "Unsupported file type — the file's Content-Type is not on the server allowlist or is empty / `application/octet-stream`.", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/UploadErrorResponse" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "500": { | ||
|
cubic-dev-ai[bot] marked this conversation as resolved.
|
||
| "description": "Internal storage error. Full details are logged server-side.", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/UploadErrorResponse" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "components": { | ||
| "securitySchemes": { | ||
| "apiKeyAuth": { | ||
| "type": "apiKey", | ||
| "in": "header", | ||
| "name": "x-api-key" | ||
| }, | ||
| "bearerAuth": { | ||
| "type": "http", | ||
| "scheme": "bearer" | ||
| } | ||
| }, | ||
| "schemas": { | ||
| "UploadResponse": { | ||
| "type": "object", | ||
| "required": [ | ||
| "success", | ||
| "fileName", | ||
| "fileType", | ||
| "fileSize", | ||
| "url" | ||
| ], | ||
| "properties": { | ||
| "success": { | ||
| "type": "boolean", | ||
| "description": "Always `true` on a 200 response.", | ||
| "example": true | ||
| }, | ||
| "fileName": { | ||
| "type": "string", | ||
| "description": "The original file name from the upload.", | ||
| "example": "cover.png" | ||
| }, | ||
| "fileType": { | ||
| "type": "string", | ||
| "description": "The MIME type of the uploaded file, exactly as provided by the client. Must be on the server allowlist.", | ||
| "example": "image/png" | ||
| }, | ||
| "fileSize": { | ||
| "type": "integer", | ||
| "description": "The size of the uploaded file in bytes.", | ||
| "example": 24576 | ||
| }, | ||
| "url": { | ||
| "type": "string", | ||
| "description": "Permanent fetchable HTTPS URL for the uploaded file.", | ||
| "example": "https://example.supabase.co/storage/v1/object/public/public-uploads/abc123.png" | ||
| } | ||
| } | ||
| }, | ||
| "UploadErrorResponse": { | ||
| "type": "object", | ||
| "required": [ | ||
| "success", | ||
| "error" | ||
| ], | ||
| "properties": { | ||
| "success": { | ||
| "type": "boolean", | ||
| "description": "Always `false` on an error response.", | ||
| "example": false | ||
| }, | ||
| "error": { | ||
| "type": "string", | ||
| "description": "Human-readable error message. For 500 errors this is intentionally generic; full details are logged server-side.", | ||
| "example": "No file provided" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,4 @@ | ||||||||||||||||
| --- | ||||||||||||||||
| title: 'Upload File' | ||||||||||||||||
| openapi: '/api-reference/openapi/upload.json POST /api/upload' | ||||||||||||||||
|
Comment on lines
+2
to
+3
There was a problem hiding this comment. Fix API-reference frontmatter metadata/format on Line 2 and Line 3. This page is missing Proposed fix ---
title: 'Upload File'
-openapi: '/api-reference/openapi/upload.json POST /api/upload'
+description: 'Upload a file and receive a permanent CDN URL.'
+openapi: 'POST /api/upload'
---📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||||||||||||
| --- | ||||||||||||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2: Custom agent: Documentation and Naming Conventions for Maintainable Code
Removed the explicit
serversarray from the OpenAPI spec, breaking documentation clarity and consistency with other API specs.Prompt for AI agents