Skip to content

docs(connectors): add POST /api/connectors/files (image upload contract) #246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 2 commits into from
Jun 20, 2026
+116 −1
Merged

docs(connectors): add POST /api/connectors/files (image upload contract) #246

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
89bb4bc
docs(connectors): document POST /api/connectors/files (image upload)
sweetmantech Jun 19, 2026
f862885
docs(connectors): address review — drop vendor name, KISS, add cross-…
sweetmantech Jun 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions api-reference/connectors/upload-file.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: 'Upload Connector File'
openapi: "/api-reference/openapi/social.json POST /api/connectors/files"

@coderabbitai coderabbitai Bot Jun 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use the required API-reference openapi format.

Line 3 is not in the required openapi: 'METHOD /path' shape, so Mintlify auto-generation may not bind this page correctly.

Suggested frontmatter fix 
-openapi: "/api-reference/openapi/social.json POST /api/connectors/files"
+openapi: "POST /api/connectors/files"

As per coding guidelines, “API reference MDX pages should be frontmatter-only … Include OpenAPI spec reference in API reference MDX frontmatter using format: openapi: 'METHOD /path'.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
openapi: "/api-reference/openapi/social.json POST /api/connectors/files"
openapi: "POST /api/connectors/files"
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/connectors/upload-file.mdx` at line 3, The openapi frontmatter
on line 3 is not in the required format. It currently includes a file path
before the HTTP method and endpoint, but the correct format should only contain
the HTTP method and the endpoint path using the structure 'METHOD /path'. Remove
the file path prefix '/api-reference/openapi/social.json' from the openapi field
and keep only 'POST /api/connectors/files' using single quotes to match the
required API-reference format.

Source: Coding guidelines

---
Comment on lines +1 to +4

@coderabbitai coderabbitai Bot Jun 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add a description field in frontmatter metadata.

This page currently has title but no description, which breaks the docs metadata convention for MDX pages.

Suggested metadata addition 
 ---
 title: 'Upload Connector File'
+description: 'Stage an external image URL for connector actions that accept file_uploadable inputs.'
 openapi: "POST /api/connectors/files"
 ---

As per coding guidelines, “Use MDX … with frontmatter for page metadata (title, description).”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
---
title: 'Upload Connector File'
openapi: "/api-reference/openapi/social.json POST /api/connectors/files"
---
---
title: 'Upload Connector File'
description: 'Stage an external image URL for connector actions that accept file_uploadable inputs.'
openapi: "POST /api/connectors/files"
---
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/connectors/upload-file.mdx` around lines 1 - 4, The frontmatter
metadata in the upload-file.mdx file is missing a required `description` field.
Add a `description` field to the frontmatter block (between the triple dashes)
along with the existing `title` and `openapi` fields. The description should be
a concise summary of what the upload connector file endpoint does, following the
docs metadata convention that requires both title and description for all MDX
pages.

Source: Coding guidelines

112 changes: 111 additions & 1 deletion api-reference/openapi/social.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -810,7 +810,7 @@
},
"post": {
"security": [{ "apiKeyAuth": [] }, { "bearerAuth": [] }],
"description": "Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific.",
"description": "Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor.",
"requestBody": {
"description": "Action to execute and the parameters for it",
"required": true,
Expand Down Expand Up @@ -895,6 +895,72 @@
}
}
}
},
"/api/connectors/files": {
"post": {
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
],
"description": "Stage an image into Connector file storage so it can be attached to a connector action that accepts a file_uploadable field. The returned descriptor is embedded in a file_uploadable array on [Execute Connector Action](/api-reference/connectors/execute-action).",
"requestBody": {
"description": "The image URL to stage and the action it will be attached to.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadConnectorFileRequest"
}
}
}
},
"responses": {
"200": {
"description": "Image staged. Returns the Connector file descriptor to embed in the action's file_uploadable array.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadConnectorFileResponse"
}
}
}
},
"400": {
"description": "Bad request — missing or invalid `url` (must be a reachable URL) or `toolSlug`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized — invalid or missing API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Upstream failure staging the file into Connector storage (the image fetch failed or Connector errored).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
Expand Down Expand Up @@ -2309,6 +2375,50 @@
"description": "ISO 8601 timestamp of when the action was executed server-side."
}
}
},
"UploadConnectorFileRequest": {
"type": "object",
"required": [
"url",
"toolSlug"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Publicly reachable URL of the image to stage. Fetched server-side and uploaded to Connector storage. Required."
},
"toolSlug": {

@cubic-dev-ai cubic-dev-ai Bot Jun 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Field named toolSlug but described as "the action slug" — inconsistent with actionSlug used by the companion ExecuteConnectorActionRequest. Consumers must use both endpoints together (upload file, then pass result to execute action) and will be confused by the different names for the same UPPERCASE_SNAKE_CASE identifier.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/social.json, line 2391:

<comment>Field named `toolSlug` but described as "the action slug" — inconsistent with `actionSlug` used by the companion ExecuteConnectorActionRequest. Consumers must use both endpoints together (upload file, then pass result to execute action) and will be confused by the different names for the same UPPERCASE_SNAKE_CASE identifier.</comment>

<file context>
@@ -2309,6 +2375,50 @@
+            "format": "uri",
+            "description": "Publicly reachable URL of the image to stage. Fetched server-side and uploaded to Composio storage. Required."
+          },
+          "toolSlug": {
+            "type": "string",
+            "description": "The action slug the image will be attached to, UPPERCASE_SNAKE_CASE (e.g. `LINKEDIN_CREATE_LINKED_IN_POST`). Scopes the upload to that tool/toolkit. Required."
</file context>

"type": "string",
"description": "The action slug the image will be attached to, UPPERCASE_SNAKE_CASE (e.g. `LINKEDIN_CREATE_LINKED_IN_POST`). Scopes the upload to that tool/toolkit. Required."
}
}
},
"UploadConnectorFileResponse": {
"type": "object",
"required": [
"success",
"name",
"mimetype",
"s3key"
],
"properties": {
"success": {
"type": "boolean"
},
"name": {
"type": "string",
"description": "Stored filename."
},
"mimetype": {
"type": "string",
"description": "Detected MIME type of the stored file."
},
"s3key": {
"type": "string",
"description": "Connector storage key. Pass this together with `name` and `mimetype` in the action's file_uploadable array."
}
}
}
}
}
Expand Down
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,6 +394,7 @@
"api-reference/connectors/authorize",
"api-reference/connectors/disconnect",
"api-reference/connectors/list-actions",
"api-reference/connectors/upload-file",
"api-reference/connectors/execute-action"
]
}
Expand Down