Upload an image to an article
Example request
Generated- cURL
- JavaScript
- TypeScript
- Python
- PHP
- Go
- Java
- Ruby
- C#
Responses
Uploads an image and returns its hosted URL, ready to reference from the article body. Send the image as a multipart file part, or pass a url query parameter to have HelpDocs fetch it from elsewhere.
Authentication
-
-
ApiKeyBearerhttpbearerAn API key sent as
Authorization: Bearer <key>. A key holds scopes, the same ones OAuth uses, and an operation needs the scope listed for it under OAuth2. A key may also expire, or be revoked or rotated in Settings > API, after which it is refused with a 401.
-
-
-
OAuth2oauth2An OAuth 2.0 access token for an app acting on behalf of a HelpDocs user, sent as
Authorization: Bearer <token>. The authorization code flow requires PKCE (S256). Each operation names the one scope it needs.
-
Path parameters
-
article_idstring Required
Query parameters
-
urlstringFetch the image from this URL instead of uploading a file.
-
purposestringSet to icon or cover when the image is the article’s icon or a cover rather than part of its body. Such an image is stored where it can be shown without a signed link, so it works in listings, link previews, and emails.
Request body
The image to upload. Omit when passing the url parameter.
multipart/form-data
-
filestring (binary) RequiredThe image file.
Responses
The hosted URL of the uploaded image.
application/json
UploadResponse
-
imagestring Required -
urlstring Required
The request was rejected: a required part is missing from the form, or a value in it is not acceptable.
text/plain
The failure, as a human-readable message.
-
string
The failure, as a human-readable message.
Authentication failed or no API key was supplied.
application/json
Error
An error response.
-
codeinteger RequiredThe HTTP status code.
-
errstring RequiredA human-readable description of the failure.
The account’s billing is past due and writes are locked. Reads keep working; editing resumes once billing is settled.
application/json
Error
An error response.
-
codeinteger RequiredThe HTTP status code.
-
errstring RequiredA human-readable description of the failure.
The key lacks write permission, or the account’s plan does not include API access.
application/json
Error
An error response.
-
codeinteger RequiredThe HTTP status code.
-
errstring RequiredA human-readable description of the failure.
No such resource in this account, or article_id does not match the pattern this route accepts.
text/plain
The failure, as a human-readable message.
-
string
The failure, as a human-readable message.
The file is larger than the account’s per-file upload limit: 5 MB, unless the plan sets a higher one.
text/plain
The failure, as a human-readable message.
-
string
The failure, as a human-readable message.
Rate limited. Wait the number of seconds in Retry-After before trying again. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset say which allowance was spent and when it refills.
-
Retry-Afterinteger -
X-RateLimit-Limitinteger -
X-RateLimit-Remaininginteger -
X-RateLimit-Resetinteger
application/json
Error
An error response.
-
codeinteger RequiredThe HTTP status code.
-
errstring RequiredA human-readable description of the failure.