Acme Store API

The Acme Store API lets you manage products, orders and customers of an Acme storefront.

All requests are made over HTTPS and return JSON. Authenticate by sending a bearer token in the Authorization header — see Authentication.

Status	Meaning
`2xx`	Success
`4xx`	Client error, check the `error` field
`5xx`	Server error, please retry

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

VariablesProduction

Name	Value
base_url	https://api.acme.dev/v1
api_token	<redacted>
store_id	store_42

Name	Value
base_url	https://staging.api.acme.dev/v1
api_token	<redacted>
store_id	store_test

Authentication

Obtain and refresh access tokens. These endpoints don't require authentication.

Log in

Authentication

POST

https://api.acme.dev/v1/auth/login

https://staging.api.acme.dev/v1/auth/login

Exchange user credentials for an access token.

The token expires after 1 hour; use Refresh token to get a new one.

Authentication

No authentication required.

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0
Content-Type	application/json

Body`application/json`

{
  "email": "jane@acme.dev",
  "password": "{{password}}",
  "remember": true
}

Example request

curl -X POST https://api.acme.dev/v1/auth/login \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "jane@acme.dev",
  "password": "{{password}}",
  "remember": true
}'

const response = await fetch("https://api.acme.dev/v1/auth/login", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "jane@acme.dev",
    "password": "{{password}}",
    "remember": true
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/auth/login"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
}
payload = {
    "email": "jane@acme.dev",
    "password": "{{password}}",
    "remember": True,
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "email": "jane@acme.dev",
  "password": "{{password}}",
  "remember": true
}`)

	req, err := http.NewRequest("POST", "https://api.acme.dev/v1/auth/login", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Content-Type", "application/json")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl -X POST https://staging.api.acme.dev/v1/auth/login \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "jane@acme.dev",
  "password": "{{password}}",
  "remember": true
}'

const response = await fetch("https://staging.api.acme.dev/v1/auth/login", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "jane@acme.dev",
    "password": "{{password}}",
    "remember": true
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/auth/login"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
}
payload = {
    "email": "jane@acme.dev",
    "password": "{{password}}",
    "remember": True,
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "email": "jane@acme.dev",
  "password": "{{password}}",
  "remember": true
}`)

	req, err := http.NewRequest("POST", "https://staging.api.acme.dev/v1/auth/login", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Content-Type", "application/json")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Example response

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "rt_8f2k...",
  "expiresIn": 3600
}

{
  "error": "invalid_credentials",
  "message": "Email or password is incorrect."
}

Refresh token

Authentication

POST

https://api.acme.dev/v1/auth/token

https://staging.api.acme.dev/v1/auth/token

Get a new access token using a refresh token (OAuth 2 style form body).

Authentication

No authentication required.

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Body`application/x-www-form-urlencoded`

Field	Value
grant_type	refresh_token
refresh_token	{{refresh_token}}

Example request

curl -X POST https://api.acme.dev/v1/auth/token \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode 'refresh_token={{refresh_token}}'

const response = await fetch("https://api.acme.dev/v1/auth/token", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    "grant_type": "refresh_token",
    "refresh_token": "{{refresh_token}}",
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/auth/token"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Content-Type": "application/x-www-form-urlencoded",
}
payload = {
    "grant_type": "refresh_token",
    "refresh_token": "{{refresh_token}}",
}

response = requests.post(url, headers=headers, data=payload)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader("grant_type=refresh_token&refresh_token=%7B%7Brefresh_token%7D%7D")

	req, err := http.NewRequest("POST", "https://api.acme.dev/v1/auth/token", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl -X POST https://staging.api.acme.dev/v1/auth/token \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode 'refresh_token={{refresh_token}}'

const response = await fetch("https://staging.api.acme.dev/v1/auth/token", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    "grant_type": "refresh_token",
    "refresh_token": "{{refresh_token}}",
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/auth/token"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Content-Type": "application/x-www-form-urlencoded",
}
payload = {
    "grant_type": "refresh_token",
    "refresh_token": "{{refresh_token}}",
}

response = requests.post(url, headers=headers, data=payload)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader("grant_type=refresh_token&refresh_token=%7B%7Brefresh_token%7D%7D")

	req, err := http.NewRequest("POST", "https://staging.api.acme.dev/v1/auth/token", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Products

Products are the items sold in your store.

Prices are always expressed in the smallest currency unit (e.g. cents).

List products

Products

GET

https://api.acme.dev/v1/stores/{{store_id}}/products

https://staging.api.acme.dev/v1/stores/{{store_id}}/products

Returns a paginated list of products, newest first.

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Query parameters

Name	Value
page	1
limit	20
searchoptional	shoes
sort	-created_at

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Example request

curl 'https://api.acme.dev/v1/stores/store_42/products?page=1&limit=20&sort=-created_at' \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}'

const response = await fetch("https://api.acme.dev/v1/stores/store_42/products?page=1&limit=20&sort=-created_at", {
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/stores/store_42/products?page=1&limit=20&sort=-created_at"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.acme.dev/v1/stores/store_42/products?page=1&limit=20&sort=-created_at", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl 'https://staging.api.acme.dev/v1/stores/store_test/products?page=1&limit=20&sort=-created_at' \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}'

const response = await fetch("https://staging.api.acme.dev/v1/stores/store_test/products?page=1&limit=20&sort=-created_at", {
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/stores/store_test/products?page=1&limit=20&sort=-created_at"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://staging.api.acme.dev/v1/stores/store_test/products?page=1&limit=20&sort=-created_at", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Example response

{
  "data": [
    {
      "id": "prod_123",
      "name": "Running shoes",
      "price": 8999,
      "currency": "USD"
    },
    {
      "id": "prod_124",
      "name": "Trail socks",
      "price": 1299,
      "currency": "USD"
    }
  ],
  "page": 1,
  "hasMore": true
}

Get a product

Products

GET

https://api.acme.dev/v1/products/:id

https://staging.api.acme.dev/v1/products/:id

Retrieve a single product by its id.

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Path parameters

Name	Value
id	prod_123

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Example request

curl https://api.acme.dev/v1/products/prod_123 \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}'

const response = await fetch("https://api.acme.dev/v1/products/prod_123", {
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/products/prod_123"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.acme.dev/v1/products/prod_123", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl https://staging.api.acme.dev/v1/products/prod_123 \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}'

const response = await fetch("https://staging.api.acme.dev/v1/products/prod_123", {
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/products/prod_123"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://staging.api.acme.dev/v1/products/prod_123", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Example response

{
  "id": "prod_123",
  "name": "Running shoes",
  "price": 8999,
  "currency": "USD",
  "inStock": true
}

{
  "error": "not_found",
  "message": "No product with id prod_999."
}

Create a product

Products

POST

https://api.acme.dev/v1/products

https://staging.api.acme.dev/v1/products

Create a new product.

{ "id": "prod_124", "status": "draft" }

The response contains the created product.

The API validates the payload and returns 422 when a field is invalid.

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0
Content-Type	application/json
Idempotency-Key	{{uuid.v4}}

Body`application/json`

{
  "name": "Running shoes",
  "price": 8999,
  "currency": "USD",
  "tags": [
    "sport",
    "shoes"
  ],
  "inStock": true,
  "dimensions": {
    "weight": 0.8,
    "unit": "kg"
  }
}

Example request

curl -X POST https://api.acme.dev/v1/products \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: {{uuid.v4}}' \
  -H 'Authorization: Bearer {{api_token}}' \
  --data-raw '{
  "name": "Running shoes",
  "price": 8999,
  "currency": "USD",
  "tags": [
    "sport",
    "shoes"
  ],
  "inStock": true,
  "dimensions": {
    "weight": 0.8,
    "unit": "kg"
  }
}'

const response = await fetch("https://api.acme.dev/v1/products", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Content-Type": "application/json",
    "Idempotency-Key": "{{uuid.v4}}",
    "Authorization": "Bearer {{api_token}}",
  },
  body: JSON.stringify({
    "name": "Running shoes",
    "price": 8999,
    "currency": "USD",
    "tags": [
      "sport",
      "shoes"
    ],
    "inStock": true,
    "dimensions": {
      "weight": 0.8,
      "unit": "kg"
    }
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/products"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Idempotency-Key": "{{uuid.v4}}",
    "Authorization": "Bearer {{api_token}}",
}
payload = {
    "name": "Running shoes",
    "price": 8999,
    "currency": "USD",
    "tags": [
        "sport",
        "shoes",
    ],
    "inStock": True,
    "dimensions": {
        "weight": 0.8,
        "unit": "kg",
    },
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "name": "Running shoes",
  "price": 8999,
  "currency": "USD",
  "tags": [
    "sport",
    "shoes"
  ],
  "inStock": true,
  "dimensions": {
    "weight": 0.8,
    "unit": "kg"
  }
}`)

	req, err := http.NewRequest("POST", "https://api.acme.dev/v1/products", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "{{uuid.v4}}")
	req.Header.Set("Authorization", "Bearer {{api_token}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl -X POST https://staging.api.acme.dev/v1/products \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: {{uuid.v4}}' \
  -H 'Authorization: Bearer {{api_token}}' \
  --data-raw '{
  "name": "Running shoes",
  "price": 8999,
  "currency": "USD",
  "tags": [
    "sport",
    "shoes"
  ],
  "inStock": true,
  "dimensions": {
    "weight": 0.8,
    "unit": "kg"
  }
}'

const response = await fetch("https://staging.api.acme.dev/v1/products", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Content-Type": "application/json",
    "Idempotency-Key": "{{uuid.v4}}",
    "Authorization": "Bearer {{api_token}}",
  },
  body: JSON.stringify({
    "name": "Running shoes",
    "price": 8999,
    "currency": "USD",
    "tags": [
      "sport",
      "shoes"
    ],
    "inStock": true,
    "dimensions": {
      "weight": 0.8,
      "unit": "kg"
    }
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/products"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Idempotency-Key": "{{uuid.v4}}",
    "Authorization": "Bearer {{api_token}}",
}
payload = {
    "name": "Running shoes",
    "price": 8999,
    "currency": "USD",
    "tags": [
        "sport",
        "shoes",
    ],
    "inStock": True,
    "dimensions": {
        "weight": 0.8,
        "unit": "kg",
    },
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "name": "Running shoes",
  "price": 8999,
  "currency": "USD",
  "tags": [
    "sport",
    "shoes"
  ],
  "inStock": true,
  "dimensions": {
    "weight": 0.8,
    "unit": "kg"
  }
}`)

	req, err := http.NewRequest("POST", "https://staging.api.acme.dev/v1/products", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "{{uuid.v4}}")
	req.Header.Set("Authorization", "Bearer {{api_token}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Example response

Location: /v1/products/prod_125
Content-Type: application/json

{
  "id": "prod_125",
  "name": "Running shoes",
  "status": "draft"
}

{
  "error": "validation_failed",
  "fields": {
    "price": "must be a positive integer"
  }
}

Update a product

Products

PATCH

https://api.acme.dev/v1/products/:id

https://staging.api.acme.dev/v1/products/:id

Partially update a product. Only the fields you send are changed.

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Path parameters

Name	Value
id	prod_123

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Body`application/json`

{
  "price": 7999
}

Example request

curl -X PATCH https://api.acme.dev/v1/products/prod_123 \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "price": 7999
}'

const response = await fetch("https://api.acme.dev/v1/products/prod_123", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "price": 7999
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/products/prod_123"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}
payload = {
    "price": 7999,
}

response = requests.patch(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "price": 7999
}`)

	req, err := http.NewRequest("PATCH", "https://api.acme.dev/v1/products/prod_123", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")
	req.Header.Set("Content-Type", "application/json")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl -X PATCH https://staging.api.acme.dev/v1/products/prod_123 \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "price": 7999
}'

const response = await fetch("https://staging.api.acme.dev/v1/products/prod_123", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "price": 7999
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/products/prod_123"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}
payload = {
    "price": 7999,
}

response = requests.patch(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "price": 7999
}`)

	req, err := http.NewRequest("PATCH", "https://staging.api.acme.dev/v1/products/prod_123", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")
	req.Header.Set("Content-Type", "application/json")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Delete a product

Products

DELETE

https://api.acme.dev/v1/products/:id

https://staging.api.acme.dev/v1/products/:id

Permanently delete a product. This cannot be undone.

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Path parameters

Name	Value
id	prod_123

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Example request

curl -X DELETE https://api.acme.dev/v1/products/prod_123 \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}'

const response = await fetch("https://api.acme.dev/v1/products/prod_123", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/products/prod_123"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}

response = requests.delete(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("DELETE", "https://api.acme.dev/v1/products/prod_123", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl -X DELETE https://staging.api.acme.dev/v1/products/prod_123 \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}'

const response = await fetch("https://staging.api.acme.dev/v1/products/prod_123", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/products/prod_123"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}

response = requests.delete(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("DELETE", "https://staging.api.acme.dev/v1/products/prod_123", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Example response

No response body

{
  "error": "conflict",
  "message": "Product has open orders."
}

Products

Images

Upload and manage product images.

Upload an image

Products › Images

POST

https://api.acme.dev/v1/products/:id/images

https://staging.api.acme.dev/v1/products/:id/images

Upload a product image (PNG or JPEG, max 5 MB).

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Path parameters

Name	Value
id	prod_123

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Body`multipart/form-data`

Field	Value
alt	Side view
file	@./shoe.png

Example request

curl -X POST https://api.acme.dev/v1/products/prod_123/images \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}' \
  -F 'alt=Side view' \
  -F 'file=@./shoe.png;type=image/png'

const form = new FormData();
form.append("alt", "Side view");
form.append("file", fileInput.files[0]); // ./shoe.png

const response = await fetch("https://api.acme.dev/v1/products/prod_123/images", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
  },
  body: form,
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/products/prod_123/images"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}
payload = {
    "alt": "Side view",
}
files = {
    "file": open("./shoe.png", "rb"),
}

response = requests.post(url, headers=headers, data=payload, files=files)
print(response.json())

package main

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

func main() {
	body := &bytes.Buffer{}
	writer := multipart.NewWriter(body)
	writer.WriteField("alt", "Side view")
	file, _ := os.Open("./shoe.png")
	defer file.Close()
	part, _ := writer.CreateFormFile("file", "shoe.png")
	io.Copy(part, file)
	writer.Close()

	req, err := http.NewRequest("POST", "https://api.acme.dev/v1/products/prod_123/images", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")
	req.Header.Set("Content-Type", writer.FormDataContentType())

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl -X POST https://staging.api.acme.dev/v1/products/prod_123/images \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}' \
  -F 'alt=Side view' \
  -F 'file=@./shoe.png;type=image/png'

const form = new FormData();
form.append("alt", "Side view");
form.append("file", fileInput.files[0]); // ./shoe.png

const response = await fetch("https://staging.api.acme.dev/v1/products/prod_123/images", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
  },
  body: form,
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/products/prod_123/images"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}
payload = {
    "alt": "Side view",
}
files = {
    "file": open("./shoe.png", "rb"),
}

response = requests.post(url, headers=headers, data=payload, files=files)
print(response.json())

package main

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

func main() {
	body := &bytes.Buffer{}
	writer := multipart.NewWriter(body)
	writer.WriteField("alt", "Side view")
	file, _ := os.Open("./shoe.png")
	defer file.Close()
	part, _ := writer.CreateFormFile("file", "shoe.png")
	io.Copy(part, file)
	writer.Close()

	req, err := http.NewRequest("POST", "https://staging.api.acme.dev/v1/products/prod_123/images", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")
	req.Header.Set("Content-Type", writer.FormDataContentType())

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Catalog

Browse the product catalog by category. Folders can be nested as deeply as you like.

Catalog

Name	Value
category	cat_shoes

Name	Value
category	cat_shoes
subcategory	sub_running

Orders

Orders placed by customers. Requires an API key with the orders:read scope.

List orders

Orders

GET

https://api.acme.dev/v1/orders

https://staging.api.acme.dev/v1/orders

List orders, optionally filtered by status.

Authentication

API Key — send X-API-Key in the headers. Inherited from folder "Orders".

Query parameters

Name	Value
status	paid

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0
Acme-VersionOrders	{{orders_version}}

Example request

curl 'https://api.acme.dev/v1/orders?status=paid' \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Acme-Version: 2025-01' \
  -H 'X-API-Key: {{orders_api_key}}'

const response = await fetch("https://api.acme.dev/v1/orders?status=paid", {
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "X-API-Key": "{{orders_api_key}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/orders?status=paid"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "X-API-Key": "{{orders_api_key}}",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.acme.dev/v1/orders?status=paid", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Acme-Version", "2025-01")
	req.Header.Set("X-API-Key", "{{orders_api_key}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl 'https://staging.api.acme.dev/v1/orders?status=paid' \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Acme-Version: 2025-01' \
  -H 'X-API-Key: {{orders_api_key}}'

const response = await fetch("https://staging.api.acme.dev/v1/orders?status=paid", {
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "X-API-Key": "{{orders_api_key}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/orders?status=paid"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "X-API-Key": "{{orders_api_key}}",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://staging.api.acme.dev/v1/orders?status=paid", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Acme-Version", "2025-01")
	req.Header.Set("X-API-Key", "{{orders_api_key}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Create an order

Orders

POST

https://api.acme.dev/v1/orders

https://staging.api.acme.dev/v1/orders

Place an order on behalf of a customer.

Authentication

Basic Auth — send Authorization: Basic <base64(username:password)>.

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0
Acme-VersionOrders	{{orders_version}}

Body`application/json`

{
  "customerId": "cus_9",
  "items": [
    {
      "productId": "prod_123",
      "quantity": 2
    }
  ]
}

Example request

curl -X POST https://api.acme.dev/v1/orders \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Acme-Version: 2025-01' \
  -H 'Content-Type: application/json' \
  -u 'merchant:{{merchant_password}}' \
  --data-raw '{
  "customerId": "cus_9",
  "items": [
    {
      "productId": "prod_123",
      "quantity": 2
    }
  ]
}'

const response = await fetch("https://api.acme.dev/v1/orders", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "Content-Type": "application/json",
    Authorization: `Basic ${btoa("merchant:{{merchant_password}}")}`,
  },
  body: JSON.stringify({
    "customerId": "cus_9",
    "items": [
      {
        "productId": "prod_123",
        "quantity": 2
      }
    ]
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/orders"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
}
payload = {
    "customerId": "cus_9",
    "items": [
        {
            "productId": "prod_123",
            "quantity": 2,
        },
    ],
}

response = requests.post(url, headers=headers, json=payload, auth=("merchant", "{{merchant_password}}"))
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "customerId": "cus_9",
  "items": [
    {
      "productId": "prod_123",
      "quantity": 2
    }
  ]
}`)

	req, err := http.NewRequest("POST", "https://api.acme.dev/v1/orders", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Acme-Version", "2025-01")
	req.Header.Set("Content-Type", "application/json")
	req.SetBasicAuth("merchant", "{{merchant_password}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl -X POST https://staging.api.acme.dev/v1/orders \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Acme-Version: 2025-01' \
  -H 'Content-Type: application/json' \
  -u 'merchant:{{merchant_password}}' \
  --data-raw '{
  "customerId": "cus_9",
  "items": [
    {
      "productId": "prod_123",
      "quantity": 2
    }
  ]
}'

const response = await fetch("https://staging.api.acme.dev/v1/orders", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "Content-Type": "application/json",
    Authorization: `Basic ${btoa("merchant:{{merchant_password}}")}`,
  },
  body: JSON.stringify({
    "customerId": "cus_9",
    "items": [
      {
        "productId": "prod_123",
        "quantity": 2
      }
    ]
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/orders"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
}
payload = {
    "customerId": "cus_9",
    "items": [
        {
            "productId": "prod_123",
            "quantity": 2,
        },
    ],
}

response = requests.post(url, headers=headers, json=payload, auth=("merchant", "{{merchant_password}}"))
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "customerId": "cus_9",
  "items": [
    {
      "productId": "prod_123",
      "quantity": 2
    }
  ]
}`)

	req, err := http.NewRequest("POST", "https://staging.api.acme.dev/v1/orders", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Acme-Version", "2025-01")
	req.Header.Set("Content-Type", "application/json")
	req.SetBasicAuth("merchant", "{{merchant_password}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Export orders (XML)

Orders

GET

https://api.acme.dev/v1/orders/export.xml

https://staging.api.acme.dev/v1/orders/export.xml

Legacy XML export.

Authentication

API Key — send X-API-Key in the headers. Inherited from folder "Orders".

Headers

Name	Value
User-Agentworkspace	acme-docs/1.0
Acme-VersionOrders	{{orders_version}}
Accept	application/xml

Example request

curl https://api.acme.dev/v1/orders/export.xml \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Acme-Version: 2025-01' \
  -H 'Accept: application/xml' \
  -H 'X-API-Key: {{orders_api_key}}'

const response = await fetch("https://api.acme.dev/v1/orders/export.xml", {
  headers: {
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "Accept": "application/xml",
    "X-API-Key": "{{orders_api_key}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/orders/export.xml"
headers = {
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "Accept": "application/xml",
    "X-API-Key": "{{orders_api_key}}",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.acme.dev/v1/orders/export.xml", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Acme-Version", "2025-01")
	req.Header.Set("Accept", "application/xml")
	req.Header.Set("X-API-Key", "{{orders_api_key}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl https://staging.api.acme.dev/v1/orders/export.xml \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Acme-Version: 2025-01' \
  -H 'Accept: application/xml' \
  -H 'X-API-Key: {{orders_api_key}}'

const response = await fetch("https://staging.api.acme.dev/v1/orders/export.xml", {
  headers: {
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "Accept": "application/xml",
    "X-API-Key": "{{orders_api_key}}",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/orders/export.xml"
headers = {
    "User-Agent": "acme-docs/1.0",
    "Acme-Version": "2025-01",
    "Accept": "application/xml",
    "X-API-Key": "{{orders_api_key}}",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://staging.api.acme.dev/v1/orders/export.xml", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Acme-Version", "2025-01")
	req.Header.Set("Accept", "application/xml")
	req.Header.Set("X-API-Key", "{{orders_api_key}}")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Example response

<?xml version="1.0"?>
<orders>
  <order id="ord_1" status="paid" total="17998"/>
</orders>

GraphQL

A GraphQL endpoint is available for flexible queries.

Search products

GraphQL

POST

https://api.acme.dev/v1/graphql

https://staging.api.acme.dev/v1/graphql

Full-text product search with GraphQL.

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Body`application/json`

query Search($term: String!) {
  products(search: $term, first: 5) {
    id
    name
    price
  }
}

Variables

{
  "term": "shoes"
}

Example request

curl -X POST https://api.acme.dev/v1/graphql \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "query": "query Search($term: String!) { products(search: $term, first: 5) { id name price } }",
  "variables": {
    "term": "shoes"
  }
}'

const query = /* GraphQL */ `
  query Search($term: String!) {
    products(search: $term, first: 5) {
      id
      name
      price
    }
  }
`;

const response = await fetch("https://api.acme.dev/v1/graphql", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query,
    variables: {
      "term": "shoes"
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/graphql"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}

query = """
query Search($term: String!) {
  products(search: $term, first: 5) {
    id
    name
    price
  }
}
"""

payload = {
    "query": query,
    "variables": {
        "term": "shoes",
    },
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	query := `
		query Search($term: String!) {
		  products(search: $term, first: 5) {
		    id
		    name
		    price
		  }
		}
	`
	variables := json.RawMessage(`{
		"term": "shoes"
	}`)

	payload, _ := json.Marshal(map[string]any{
		"query":     query,
		"variables": variables,
	})

	req, err := http.NewRequest("POST", "https://api.acme.dev/v1/graphql", bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")
	req.Header.Set("Content-Type", "application/json")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl -X POST https://staging.api.acme.dev/v1/graphql \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "query": "query Search($term: String!) { products(search: $term, first: 5) { id name price } }",
  "variables": {
    "term": "shoes"
  }
}'

const query = /* GraphQL */ `
  query Search($term: String!) {
    products(search: $term, first: 5) {
      id
      name
      price
    }
  }
`;

const response = await fetch("https://staging.api.acme.dev/v1/graphql", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query,
    variables: {
      "term": "shoes"
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/graphql"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
    "Authorization": "Bearer {{api_token}}",
}

query = """
query Search($term: String!) {
  products(search: $term, first: 5) {
    id
    name
    price
  }
}
"""

payload = {
    "query": query,
    "variables": {
        "term": "shoes",
    },
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	query := `
		query Search($term: String!) {
		  products(search: $term, first: 5) {
		    id
		    name
		    price
		  }
		}
	`
	variables := json.RawMessage(`{
		"term": "shoes"
	}`)

	payload, _ := json.Marshal(map[string]any{
		"query":     query,
		"variables": variables,
	})

	req, err := http.NewRequest("POST", "https://staging.api.acme.dev/v1/graphql", bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")
	req.Header.Set("Authorization", "Bearer {{api_token}}")
	req.Header.Set("Content-Type", "application/json")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Realtime

Streaming APIs over WebSockets and gRPC.

Order updates

Realtime

wss://stream.acme.dev/orders

Subscribe to real-time order events.

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Query parameters

Name	Value
store	{{store_id}}

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Message

{
  "subscribe": "orders.*"
}

Example request

// Note: browsers don't support custom WebSocket headers. In Node.js, use the `ws` package:
// new WebSocket(url, { headers: {"Accept":"application/json","User-Agent":"acme-docs/1.0","Authorization":"Bearer {{api_token}}"} })
const socket = new WebSocket("wss://stream.acme.dev/orders?store=store_42");

socket.addEventListener("open", () => {
  socket.send("{\"subscribe\": \"orders.*\"}");
});

socket.addEventListener("message", (event) => {
  console.log(event.data);
});

wscat -c 'wss://stream.acme.dev/orders?store=store_42' \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}'

# Then send:
# {"subscribe": "orders.*"}

// Note: browsers don't support custom WebSocket headers. In Node.js, use the `ws` package:
// new WebSocket(url, { headers: {"Accept":"application/json","User-Agent":"acme-docs/1.0","Authorization":"Bearer {{api_token}}"} })
const socket = new WebSocket("wss://stream.acme.dev/orders?store=store_test");

socket.addEventListener("open", () => {
  socket.send("{\"subscribe\": \"orders.*\"}");
});

socket.addEventListener("message", (event) => {
  console.log(event.data);
});

wscat -c 'wss://stream.acme.dev/orders?store=store_test' \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0' \
  -H 'Authorization: Bearer {{api_token}}'

# Then send:
# {"subscribe": "orders.*"}

Get stock level

Realtime

gRPC

http://grpc.acme.dev:50051

acme.inventory.v1.Inventory/GetStock

Query live inventory via gRPC.

Authentication

Bearer Token — send Authorization: Bearer <token>. Inherited from workspace "Acme Store API".

Metadata

Name	Value
x-store-id	{{store_id}}

Message

{
  "productId": "prod_123"
}

Example request

grpcurl \
  -plaintext \
  -H 'x-store-id: store_42' \
  -H 'authorization: Bearer {{api_token}}' \
  -d '{
  "productId": "prod_123"
}' \
  grpc.acme.dev:50051 \
  acme.inventory.v1.Inventory/GetStock

grpcurl \
  -plaintext \
  -H 'x-store-id: store_test' \
  -H 'authorization: Bearer {{api_token}}' \
  -d '{
  "productId": "prod_123"
}' \
  grpc.acme.dev:50051 \
  acme.inventory.v1.Inventory/GetStock

Health check

GET

https://api.acme.dev/v1/health

https://staging.api.acme.dev/v1/health

Returns ok when the API is up. No authentication required.

Authentication

No authentication required.

Headers

Name	Value
Acceptworkspace	application/json
User-Agentworkspace	acme-docs/1.0

Example request

curl https://api.acme.dev/v1/health \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0'

const response = await fetch("https://api.acme.dev/v1/health", {
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.acme.dev/v1/health"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.acme.dev/v1/health", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

curl https://staging.api.acme.dev/v1/health \
  -H 'Accept: application/json' \
  -H 'User-Agent: acme-docs/1.0'

const response = await fetch("https://staging.api.acme.dev/v1/health", {
  headers: {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.api.acme.dev/v1/health"
headers = {
    "Accept": "application/json",
    "User-Agent": "acme-docs/1.0",
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://staging.api.acme.dev/v1/health", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "acme-docs/1.0")

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

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Example response

ok

Retry-After: 30
Cache-Control: no-store

{
  "status": "degraded",
  "checks": {
    "database": "down"
  }
}

Acme Store API

Authentication

VariablesProduction

Authentication

Headers

Bodyapplication/json

Authentication

Headers

Bodyapplication/x-www-form-urlencoded

Authentication

Query parameters

Headers

Authentication

Path parameters

Headers

Authentication

Headers

Bodyapplication/json

Authentication

Path parameters

Headers

Bodyapplication/json

Authentication

Path parameters

Headers

Authentication

Path parameters

Headers

Bodymultipart/form-data

Authentication

Headers

Authentication

Path parameters

Headers

Authentication

Path parameters

Headers

Authentication

Query parameters

Headers

Authentication

Headers

Bodyapplication/json

Authentication

Headers

Authentication

Headers

Bodyapplication/json

Authentication

Query parameters

Headers

Message

Authentication

Metadata

Message

Authentication

Headers

Body`application/json`

Body`application/x-www-form-urlencoded`

Body`application/json`

Body`application/json`

Body`multipart/form-data`

Body`application/json`

Body`application/json`