Authentication and requests

Choose the access type

• Public access: an operation can accept a request without a signed-in account. Content restrictions and rate limits can still apply.
• Account required: the request needs a valid account session and permission for the resource. Another user's resource identifier does not grant access.
• Authentication flow: follow the sign-in, verification or broker connection steps. A callback depends on state from the earlier step.

Use https://api.weavers.app for the API service. Website /api/ helpers have separate behavior. The signed-in APIs also power Weavers itself; their presence here does not provide a general-purpose customer API-key provisioning service.

Account sessions

• The standard sign-in flow sets a secure HttpOnly session cookie in production. The browser sends it with credentialed requests.
• Session authentication can accept a supported Bearer token or the session cookie. A token must pass the server's verification and permission checks; an arbitrary API key cannot replace it.
• Browser requests must come from an allowed origin. CORS configuration does not grant access to another account's resources.
• Use GET /api/auth/check to inspect sign-in state and GET /api/auth/csrf to set the CSRF cookie for the browser flow. Keep credentials out of URLs, logs and shared examples.

const response = await fetch("https://api.weavers.app/api/me", {
  credentials: "include",
  signal: AbortSignal.timeout(15000),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const profile = await response.json();

Send a write request

• Send JSON with Content-Type: application/json when the operation expects a JSON body. File and stream operations use their own content type.
• Where CSRF protection applies, send an allowed Origin, the CSRF cookie, and the same value in X-CSRF-Token. A Bearer header does not automatically bypass this check.
• Use only the fields the operation accepts. Unknown fields can fail validation. Each operation page describes its nested request and response models.
• Read the current resource before changing it. Creation, deletion, publication, credit transfers and broker orders have different side effects.

Retries and replay protection

• For operations marked with replay protection, generate a fresh X-Request-Nonce for each HTTP attempt: 16–128 letters, digits, underscores or hyphens.
• Send a current numeric X-Request-Timestamp: ten-digit Unix seconds or thirteen-digit Unix milliseconds. The deployed clock window controls acceptance; ISO date strings are not accepted.
• An X-Idempotency-Key, when required, uses 8–128 letters, digits, underscores or hyphens. Retain it for retries of the same logical action where that operation implements idempotency.
• A nonce prevents replay of an HTTP attempt. An idempotency key identifies an action. They serve different purposes; accepting the header alone is not a universal exactly-once guarantee.
• After an ambiguous write timeout, inspect the resource or job before retrying. Respect Retry-After when returned.

Responses and asynchronous jobs

• Check status and Content-Type before parsing. A successful operation can return JSON, a redirect, image data, a stream or an empty response.
• A 202 response means a request was accepted, not that the work finished. Retain the job/request identifier and use its status operation.
• Returned collections can be empty. Nullable fields mean unavailable or inapplicable data. Pagination, ordering and date formats are operation-specific.
• The downloadable OpenAPI file covers all 211 customer-facing HTTP operations, including account actions, uploads and browser flows.

Errors and limits

• 400: malformed input, missing fields or invalid request headers.
• 401: authentication is missing or invalid.
• 403: permission, origin, CSRF or another access check failed.
• 404: the resource or enabled capability is unavailable; some operations conceal resources you cannot access.
• 409: conflict or a detected replay. Check the operation's error code before retrying.
• 429: request limit reached. Honor Retry-After when supplied and use bounded backoff.
• 5xx: a server, dependency or configuration failure. Avoid blindly retrying state-changing requests.

JSON errors commonly contain error and sometimes code; the exact envelope and extra fields depend on the operation. Fixed production quotas are not promised by this documentation. Authentication, resource and infrastructure limits may all apply.