API Endpoints Reference

The RedCore SDK exposes every REST endpoint as a typed Python/Node.js/Go method. This page documents each endpoint with its full request parameters, response schema, and status codes. All request and response bodies use JSON.

Note

Rate limit: 1 000 requests per minute per API key. Exceeding this returns 429 Too Many Requests. See Errors & Status Codes for the RATE_LIMIT_EXCEEDED error and retry guidance.

User Management

User Object

All user endpoints share the same User response schema:

Field	Type	Description
`id`	`string`	Unique resource identifier (prefix: `usr_`).
`email`	`string`	Primary email address. Unique per organization.
`name`	`string`	Full display name.
`role`	`string`	One of `admin`, `editor`, or `viewer`.
`status`	`string`	One of `active`, `inactive`, or `pending_invite`.
`created_at`	`string (ISO 8601)`	Timestamp when the record was created.
`updated_at`	`string (ISO 8601)`	Timestamp of the most recent change.

List Users

GET /users

Returns a paginated list of all users in the authenticated organization, ordered by created_at descending.

Request Headers:

Authorization -- Bearer <access_token> — required.
Accept -- application/json

Query Parameters:

limit -- Maximum results per page. Default 20, max 100.
offset -- Results to skip. Default 0.
role -- Filter by role: admin, editor, or viewer.
status -- Filter by status: active, inactive, or pending_invite.
q -- Partial-match search across name and email.

Status Codes:

200 OK -- Paginated array of User objects.
401 Unauthorized -- Missing or expired token.
403 Forbidden -- Token lacks the users:read scope.
429 Too Many Requests -- Rate limit exceeded.

Example request:

List active admin users

curl -X GET "https://api.redcore.com/v1/users?role=admin&status=active&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example response (200 OK):

GET /v1/users — response body

{
  "data": [
    {
      "id":         "usr_98765",
      "email":      "alice@example.com",
      "name":       "Alice Müller",
      "role":       "admin",
      "status":     "active",
      "created_at": "2025-11-15T08:30:00Z",
      "updated_at": "2026-04-01T14:22:00Z"
    }
  ],
  "meta": { "total": 42, "limit": 10, "offset": 0 }
}

SDK usage:

Python — list all users with automatic pagination

for page in client.users.list_all(status="active", page_size=50):
    for user in page:
        print(user.id, user.email)

Retrieve a User

GET /users/(string: user_id)

Retrieve a single user record by unique identifier.

Parameters:

user_id -- The usr_-prefixed user ID.

Request Headers:

Authorization -- Bearer <access_token> — required.

Status Codes:

200 OK -- Single User object.
401 Unauthorized -- Missing or expired token.
403 Forbidden -- Token lacks the users:read scope.
404 Not Found -- User not found.

Example request:

Retrieve user usr_98765

curl -X GET "https://api.redcore.com/v1/users/usr_98765" \
  -H "Authorization: Bearer YOUR_TOKEN"

SDK usage:

Python

from redcore.exceptions import NotFoundError

try:
    user = client.users.get("usr_98765")
    print(user.name, user.role)
except NotFoundError:
    print("User does not exist.")

Create a User

POST /users

Create a new user in the organization. Sends an invitation email to the supplied address.

Request Headers:

Authorization -- Bearer <access_token> — required.
Content-Type -- application/json

JSON Parameters:

email (string) -- Required. Email address of the new user.
name (string) -- Required. Full display name.
role (string) -- Required. One of admin, editor, viewer.

Status Codes:

201 Created -- User created. Location header points to the new resource.
400 Bad Request -- Missing or invalid fields — see details array.
401 Unauthorized -- Missing or expired token.
403 Forbidden -- Token lacks the users:write scope.
409 Conflict -- A user with that email already exists.

Example request:

Create a new editor user

curl -X POST "https://api.redcore.com/v1/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "bob@example.com", "name": "Bob Smith", "role": "editor"}'

SDK usage:

Python

from redcore.exceptions import ValidationError, DuplicateError

try:
    new_user = client.users.create(
        email="bob@example.com",
        name="Bob Smith",
        role="editor",
    )
    print(f"Invited: {new_user.id}")
except ValidationError as exc:
    for detail in exc.details:
        print(detail["field"], detail["issue"])
except DuplicateError:
    print("A user with this email already exists.")

Update a User

PATCH /users/(string: user_id)

Partially update a user record. Only the supplied fields are modified; omitted fields remain unchanged.

Parameters:

user_id -- The usr_-prefixed user ID.

Request Headers:

Authorization -- Bearer <access_token> — required.
Content-Type -- application/json

JSON Parameters:

name (string) -- New display name.
role (string) -- New role: admin, editor, or viewer.
status (string) -- New status: active or inactive.

Status Codes:

200 OK -- Updated User object.
400 Bad Request -- Invalid field value.
401 Unauthorized -- Missing or expired token.
403 Forbidden -- Token lacks the users:write scope.
404 Not Found -- User not found.

Example request:

Promote a user to admin

curl -X PATCH "https://api.redcore.com/v1/users/usr_98765" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

SDK usage:

Python

updated = client.users.update("usr_98765", role="admin")
print(updated.role)   # → "admin"

Delete a User

DELETE /users/(string: user_id)

Permanently deactivate and remove a user from the organization. This action is irreversible.

Parameters:

user_id -- The usr_-prefixed user ID.

Request Headers:

Authorization -- Bearer <access_token> — required.

Status Codes:

204 No Content -- User deleted. No response body.
401 Unauthorized -- Missing or expired token.
403 Forbidden -- Token lacks the users:write scope.
404 Not Found -- User not found.

Danger

Deleting a user immediately revokes all their active sessions and tokens. Any resources exclusively owned by the user must be reassigned beforehand to avoid data loss.

Example request:

Delete user usr_98765

curl -X DELETE "https://api.redcore.com/v1/users/usr_98765" \
  -H "Authorization: Bearer YOUR_TOKEN"

SDK usage:

Python

client.users.delete("usr_98765")   # raises NotFoundError if missing

Product Catalog

Product Object

Field	Type	Description
`id`	`string`	Unique resource identifier (prefix: `prod_`).
`name`	`string`	Human-readable product name.
`sku`	`string`	Stock-keeping unit. Unique per catalog.
`price`	`number`	Unit price in the organization's base currency (e.g., USD cents).
`stock`	`integer`	Units currently available.
`status`	`string`	One of `available`, `out_of_stock`, or `discontinued`.
`created_at`	`string (ISO 8601)`	Timestamp when the product was added to the catalog.

List Products

GET /products

Returns a paginated list of products in the catalog.

Request Headers:

Authorization -- Bearer <access_token> — required.

Query Parameters:

limit -- Max results per page. Default 20, max 100.
offset -- Results to skip. Default 0.
status -- Filter by status: available, out_of_stock, discontinued.
q -- Full-text search across name and sku.

Status Codes:

200 OK -- Paginated array of Product objects.
401 Unauthorized -- Missing or expired token.
403 Forbidden -- Token lacks the products:read scope.
429 Too Many Requests -- Rate limit exceeded.

Example request:

Fetch the first 5 available products

curl -X GET "https://api.redcore.com/v1/products?status=available&limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example response (200 OK):

GET /v1/products — response body

{
  "data": [
    {
      "id":         "prod_00123",
      "name":       "Titanium Widget Pro",
      "sku":        "TWP-001",
      "price":      4999,
      "stock":      250,
      "status":     "available",
      "created_at": "2026-01-10T12:00:00Z"
    }
  ],
  "meta": { "total": 87, "limit": 5, "offset": 0 }
}

Retrieve a Product

GET /products/(string: product_id)

Retrieve a single product by its unique identifier.

Parameters:

product_id -- The prod_-prefixed product ID.

Request Headers:

Authorization -- Bearer <access_token> — required.

Status Codes:

200 OK -- Single Product object.
401 Unauthorized -- Missing or expired token.
404 Not Found -- Product not found.

Example request:

Retrieve product prod_00123

curl -X GET "https://api.redcore.com/v1/products/prod_00123" \
  -H "Authorization: Bearer YOUR_TOKEN"

SDK usage:

Python

product = client.products.get("prod_00123")
print(f"{product.name} — ${product.price / 100:.2f}")

Pagination

All list endpoints use offset-based pagination. The meta block in every response provides the values you need to walk through pages:

Python — generic paginator helper

def iter_pages(list_fn, **kwargs):
    """Yield individual items from any SDK list method."""
    limit, offset = kwargs.pop("limit", 100), 0
    while True:
        page = list_fn(limit=limit, offset=offset, **kwargs)
        yield from page["data"]
        if offset + limit >= page["meta"]["total"]:
            break
        offset += limit

# Usage
for user in iter_pages(client.users.list, status="active"):
    print(user["email"])