$ cat README.md

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

Variables(Production)

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.

# Authentication

Log in

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0
Content-Type	application/json

Bodyapplication/json

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

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

response

HTTP/1.1 200 OK

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

HTTP/1.1 401 Unauthorized

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

HTTP/1.1 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

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

Bodyapplication/x-www-form-urlencoded

Field	Value
grant_type	refresh_token
refresh_token	{{refresh_token}}

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

# Products

List 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
search[optional]	shoes
sort	-created_at

Headers

Name	Value
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

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

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
}

# Products

Get a product

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

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

response

HTTP/1.1 200 OK

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

HTTP/1.1 404 Not Found

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

# Products

Create a product

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0
Content-Type	application/json
Idempotency-Key	{{uuid.v4}}

Bodyapplication/json

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

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

response

HTTP/1.1 201 Created

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

HTTP/1.1 422 Unprocessable Content

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

# Products

Update a product

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

Bodyapplication/json

{
  "price": 7999
}

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

# Products

Delete a product

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

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

response

HTTP/1.1 204 No Content

# no body

HTTP/1.1 409 Conflict

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

# Products

Images

Upload and manage product images.

# Products / Images

Upload an image

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

Bodymultipart/form-data

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

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.

# Orders

List 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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0
Acme-Version[from Orders]	{{orders_version}}

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

# Orders

Create an order

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0
Acme-Version[from Orders]	{{orders_version}}

Bodyapplication/json

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

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

# Orders

Export orders (XML)

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-Agent[workspace]	acme-docs/1.0
Acme-Version[from Orders]	{{orders_version}}
Accept	application/xml

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

response

HTTP/1.1 200 OK

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

GraphQL

A GraphQL endpoint is available for flexible queries.

# GraphQL

Search products

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

Bodyapplication/json

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

# variables

{
  "term": "shoes"
}

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.

# Realtime

Order updates

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

Message

{
  "subscribe": "orders.*"
}

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

# Realtime

Get stock level

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

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
Accept[workspace]	application/json
User-Agent[workspace]	acme-docs/1.0

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

response

HTTP/1.1 200 OK

ok

HTTP/1.1 503 Service Unavailable

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