General arrangement

Acme Store API

General notes

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

Variables · Production

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

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

Section

Authentication

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

Authentication

Log in

Endpoint

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

Item	Name	Value
1	Acceptworkspace	application/json
2	User-Agentworkspace	acme-docs/1.0
3	Content-Type	application/json

Bodyapplication/json

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

Detail A

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))
}

Detail B

200 OK

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

401 Unauthorized

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

429 Too Many Requests

Retry-After: 30
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0

{
  "error": "rate_limited",
  "message": "Too many login attempts. Try again in 30 seconds."
}

Authentication

Refresh token

Endpoint

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

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

Bodyapplication/x-www-form-urlencoded

Item	Field	Value
1	grant_type	refresh_token
2	refresh_token	{{refresh_token}}

Detail A

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))
}

Section

Products

Products are the items sold in your store.

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

Products

List products

Endpoint

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

Item	Name	Value
1	page	1
2	limit	20
3	searchoptional	shoes
4	sort	-created_at

Headers

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

Detail A

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))
}

Detail B

{
  "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
}

Products

Get a product

Endpoint

GET

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

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

1id= prod_123

Retrieve a single product by its id.

Authentication

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

Path parameters

Item	Name	Value
1	id	prod_123

Headers

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

Detail A

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))
}

Detail B

200 OK

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

404 Not Found

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

Products

Create a product

Endpoint

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

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

Bodyapplication/json

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

Detail A

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))
}

Detail B

201 Created

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

422 Unprocessable Content

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

Products

Update a product

Endpoint

PATCH

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

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

1id= prod_123

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

Item	Name	Value
1	id	prod_123

Headers

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

Bodyapplication/json

{
  "price": 7999
}

Detail A

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))
}

Products

Delete a product

Endpoint

DELETE

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

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

1id= prod_123

Permanently delete a product. This cannot be undone.

Authentication

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

Path parameters

Item	Name	Value
1	id	prod_123

Headers

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

Detail A

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))
}

Detail B

204 No Content

No response body

409 Conflict

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

Section · Products

Images

Upload and manage product images.

Products / Images

Upload an image

Endpoint

POST

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

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

1id= prod_123

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

Item	Name	Value
1	id	prod_123

Headers

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

Bodymultipart/form-data

Item	Field	Value
1	alt	Side view
2	file	@./shoe.png

Detail A

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))
}

Section

Catalog

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

Section · Catalog

Item	Name	Value
1	category	cat_shoes

Item	Name	Value
1	category	cat_shoes
2	subcategory	sub_running

Orders

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

Orders

List orders

Endpoint

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

Item	Name	Value
1	status	paid

Headers

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

Detail A

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))
}

Orders

Create an order

Endpoint

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

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

Bodyapplication/json

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

Detail A

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))
}

Orders

Export orders (XML)

Endpoint

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

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

Detail A

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))
}

Detail B

200 OK

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

Section

GraphQL

A GraphQL endpoint is available for flexible queries.

GraphQL

Search products

Endpoint

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

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

Bodyapplication/json

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

Variables

{
  "term": "shoes"
}

Detail A

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))
}

Section

Realtime

Streaming APIs over WebSockets and gRPC.

Realtime

Order updates

Connection

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

Item	Name	Value
1	store	{{store_id}}

Headers

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

Message

{
  "subscribe": "orders.*"
}

Detail A

// 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.*"}

Realtime

Get stock level

gRPC call

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

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

Message

{
  "productId": "prod_123"
}

Detail A

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

Endpoint

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

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

Detail A

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))
}

Detail B

200 OK

ok

503 Service Unavailable

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