Skip to main content
Support

Upload an image to an article

POST https://api.helpdocs.io/v1/article/{article_id}/image

Example request

Generated
Parameters
curl -X POST 'https://api.helpdocs.io/v1/article/07elszGNU1/image?url=string&purpose=string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F file=@/path/to/file
curl -X POST https://api.helpdocs.io/v1/article/07elszGNU1/image \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F file=@/path/to/file
// The bytes to upload: a File from an <input type="file"> in the browser,
// or `await readFile("/path/to/file")` in Node.
const file = new Blob([]);

const url = "https://api.helpdocs.io/v1/article/07elszGNU1/image?url=string&purpose=string";

const form = new FormData();
form.append("file", file);

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  body: form,
});

const data = await response.json();
console.log(data);
// The bytes to upload: a File from an <input type="file"> in the browser,
// or `await readFile("/path/to/file")` in Node.
const file = new Blob([]);

const url = "https://api.helpdocs.io/v1/article/07elszGNU1/image";

const form = new FormData();
form.append("file", file);

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  body: form,
});

const data = await response.json();
console.log(data);
// The bytes to upload: a File from an <input type="file"> in the browser,
// or `await readFile("/path/to/file")` in Node.
const file = new Blob([]);

const url = "https://api.helpdocs.io/v1/article/07elszGNU1/image?url=string&purpose=string";

const form = new FormData();
form.append("file", file);

const options: RequestInit = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  body: form,
};

const response = await fetch(url, options);

const data: unknown = await response.json();
console.log(data);
// The bytes to upload: a File from an <input type="file"> in the browser,
// or `await readFile("/path/to/file")` in Node.
const file = new Blob([]);

const url = "https://api.helpdocs.io/v1/article/07elszGNU1/image";

const form = new FormData();
form.append("file", file);

const options: RequestInit = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  body: form,
};

const response = await fetch(url, options);

const data: unknown = await response.json();
console.log(data);
import requests

url = "https://api.helpdocs.io/v1/article/07elszGNU1/image"

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}

params = {
    "url": "string",
    "purpose": "string",
}

files = {
    "file": open("/path/to/file", "rb"),
}

response = requests.post(url, headers=headers, params=params, files=files)

print(response.json())
import requests

url = "https://api.helpdocs.io/v1/article/07elszGNU1/image"

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}

files = {
    "file": open("/path/to/file", "rb"),
}

response = requests.post(url, headers=headers, files=files)

print(response.json())
<?php

$ch = curl_init("https://api.helpdocs.io/v1/article/07elszGNU1/image?url=string&purpose=string");

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_TOKEN",
    ],
    CURLOPT_POSTFIELDS => [
        "file" => new CURLFile("/path/to/file"),
    ],
]);

$response = curl_exec($ch);

print_r(json_decode($response, true));
<?php

$ch = curl_init("https://api.helpdocs.io/v1/article/07elszGNU1/image");

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_TOKEN",
    ],
    CURLOPT_POSTFIELDS => [
        "file" => new CURLFile("/path/to/file"),
    ],
]);

$response = curl_exec($ch);

print_r(json_decode($response, true));
package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var body bytes.Buffer
	form := multipart.NewWriter(&body)
	file, err := os.Open("/path/to/file")
	if err != nil {
		panic(err)
	}
	defer file.Close()
	part, err := form.CreateFormFile("file", "file")
	if err != nil {
		panic(err)
	}
	if _, err := io.Copy(part, file); err != nil {
		panic(err)
	}
	if err := form.Close(); err != nil {
		panic(err)
	}

	req, err := http.NewRequest(http.MethodPost, "https://api.helpdocs.io/v1/article/07elszGNU1/image?url=string&purpose=string", &body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
	req.Header.Set("Content-Type", form.FormDataContentType())

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}
package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var body bytes.Buffer
	form := multipart.NewWriter(&body)
	file, err := os.Open("/path/to/file")
	if err != nil {
		panic(err)
	}
	defer file.Close()
	part, err := form.CreateFormFile("file", "file")
	if err != nil {
		panic(err)
	}
	if _, err := io.Copy(part, file); err != nil {
		panic(err)
	}
	if err := form.Close(); err != nil {
		panic(err)
	}

	req, err := http.NewRequest(http.MethodPost, "https://api.helpdocs.io/v1/article/07elszGNU1/image", &body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
	req.Header.Set("Content-Type", form.FormDataContentType())

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        String boundary = "----sample-boundary-" + System.nanoTime();
        List<byte[]> parts = new ArrayList<>();
        parts.add(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"file\"\r\nContent-Type: application/octet-stream\r\n\r\n").getBytes(StandardCharsets.UTF_8));
        parts.add(Files.readAllBytes(Path.of("/path/to/file")));
        parts.add("\r\n".getBytes(StandardCharsets.UTF_8));
        parts.add(("--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8));

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.helpdocs.io/v1/article/07elszGNU1/image?url=string&purpose=string"))
            .header("Authorization", "Bearer YOUR_TOKEN")
            .header("Content-Type", "multipart/form-data; boundary=" + boundary)
            .POST(HttpRequest.BodyPublishers.ofByteArrays(parts))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        String boundary = "----sample-boundary-" + System.nanoTime();
        List<byte[]> parts = new ArrayList<>();
        parts.add(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"file\"\r\nContent-Type: application/octet-stream\r\n\r\n").getBytes(StandardCharsets.UTF_8));
        parts.add(Files.readAllBytes(Path.of("/path/to/file")));
        parts.add("\r\n".getBytes(StandardCharsets.UTF_8));
        parts.add(("--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8));

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.helpdocs.io/v1/article/07elszGNU1/image"))
            .header("Authorization", "Bearer YOUR_TOKEN")
            .header("Content-Type", "multipart/form-data; boundary=" + boundary)
            .POST(HttpRequest.BodyPublishers.ofByteArrays(parts))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
require "json"
require "net/http"

uri = URI("https://api.helpdocs.io/v1/article/07elszGNU1/image?url=string&purpose=string")

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"
request.set_form(
  [
    ["file", File.open("/path/to/file")],
  ],
  "multipart/form-data",
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

pp JSON.parse(response.body)
require "json"
require "net/http"

uri = URI("https://api.helpdocs.io/v1/article/07elszGNU1/image")

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"
request.set_form(
  [
    ["file", File.open("/path/to/file")],
  ],
  "multipart/form-data",
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

pp JSON.parse(response.body)
var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.helpdocs.io/v1/article/07elszGNU1/image?url=string&purpose=string");
request.Headers.Add("Authorization", "Bearer YOUR_TOKEN");

var form = new MultipartFormDataContent();
form.Add(new StreamContent(File.OpenRead("/path/to/file")), "file", "file");
request.Content = form;

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());
var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.helpdocs.io/v1/article/07elszGNU1/image");
request.Headers.Add("Authorization", "Bearer YOUR_TOKEN");

var form = new MultipartFormDataContent();
form.Add(new StreamContent(File.OpenRead("/path/to/file")), "file", "file");
request.Content = form;

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Responses

{
  "image": "string",
  "url": "string"
}

The hosted URL of the uploaded image.

Schemas
string

The request was rejected: a required part is missing from the form, or a value in it is not acceptable.

Schemas
{
  "code": 1,
  "err": "string"
}

Authentication failed or no API key was supplied.

Schemas
{
  "code": 1,
  "err": "string"
}

The account’s billing is past due and writes are locked. Reads keep working; editing resumes once billing is settled.

Schemas
{
  "code": 1,
  "err": "string"
}

The key lacks write permission, or the account’s plan does not include API access.

Schemas
string

No such resource in this account, or article_id does not match the pattern this route accepts.

Schemas
string

The file is larger than the account’s per-file upload limit: 5 MB, unless the plan sets a higher one.

Schemas
{
  "code": 1,
  "err": "string"
}

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.

Schemas
Generated

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

    • ApiKeyBearer http bearer

      An 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.

    • OAuth2 oauth2

      An 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.

      Scopes write:articles

Path parameters

  • article_id string Required

    pattern ^[0-9a-zA-Z]{10}$

Query parameters

  • url string

    Fetch the image from this URL instead of uploading a file.

  • purpose string

    Set 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
  • file string (binary) Required

    The image file.

Responses

200

The hosted URL of the uploaded image.

application/json UploadResponse
  • image string Required
  • url string Required
400

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.

401

Authentication failed or no API key was supplied.

application/json Error

An error response.

  • code integer Required

    The HTTP status code.

  • err string Required

    A human-readable description of the failure.

402

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.

  • code integer Required

    The HTTP status code.

  • err string Required

    A human-readable description of the failure.

403

The key lacks write permission, or the account’s plan does not include API access.

application/json Error

An error response.

  • code integer Required

    The HTTP status code.

  • err string Required

    A human-readable description of the failure.

404

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.

413

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.

429

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.

headers

  • Retry-After integer
  • X-RateLimit-Limit integer
  • X-RateLimit-Remaining integer
  • X-RateLimit-Reset integer
application/json Error

An error response.

  • code integer Required

    The HTTP status code.

  • err string Required

    A human-readable description of the failure.

All endpoints