Skip to content
docs Explore the platform

ANTSAND · GUIDE

API gates and test strategy

> Production API availability: use /api/v1/help?view=guides and the resource operations catalog before following a recipe. Some localhost capabilities are not deployed yet; an absent operation is unavailable.

Existing protection is uneven

Antsand already has useful rejection mechanisms: API-key scopes, owner checks, field validation, Databoard patch dry-run, Forms settings hashes, Resume revisions, published ebook chapter hashes and research-intake validation. These mechanisms are not identical across every module.

The module reference records what exists. It does not certify all mutations, rollback behavior or generated-site workflows. A registered action or a passing happy-path test is not enough.

Use the right credential

The versioned API uses an active user-owned key. Missing or invalid keys return 401; a missing required scope returns 403 through ApiKeyAuth. authAny means one of its listed scopes is accepted, not that all are required. Resource ownership is checked separately.

Browser actions require their normal session/ACL protections. Labs has a distinct machine-token allowlist. Generated member sessions belong to their generated site. Never reuse one credential type as an assumed substitute for another.

Error handling for agents

  • 400: correct the request shape or required values before retrying.
  • 401: establish a valid credential; do not fall back to an anonymous write.
  • 403: the operation is outside the permitted scope or resource access.
  • 404: treat the record as unavailable. Do not infer another owner's data exists.
  • 409: fetch the current revision, compare changes and prepare a new request.
  • 413: reduce the payload to the documented limit.
  • 422: inspect the binding or domain validation error for that endpoint.
  • 5xx or a timeout: inspect whether the operation committed before retrying a write.

These are conventions implemented by particular handlers, not a guarantee that every legacy action uses the same response envelope. Check success/error fields and the documented response as well as HTTP status.

A test matrix for each writable resource

On an isolated fixture, test a valid request, absent credentials, insufficient scope, another owner, invalid types, missing required fields, stale revisions, unsupported fields and repeated requests. Capture the before/after record and prove rejected writes did not modify it.

Add resource-specific cases. Forms need CSRF/session and delivery behavior. Ecommerce needs checkout, webhook, refund and entitlement checks. Published content needs withdrawal and regeneration tests. A mail operation needs preview and delivery checks without accidentally sending during a generic smoke run.

Validate through HTTP

External agents communicate with Antsand through its HTTP API. They do not need PHP, Python, repository files, database access or a local key file. Obtain the service origin and a scoped API key from the operator; keep the key private.

In the examples below, API_URL means the service origin followed by /api/v1. curl illustrates HTTP requests; any HTTP client can send the same requests.

Examplehttp
GET /api/v1/help?view=guides
GET /api/v1/help?view=guide&resource=notes
GET /api/v1/help?view=schema&resource=notes
GET /api/v1/me
Authorization: Bearer YOUR_SCOPED_KEY

The help catalog is public-safe; /me requires your key. Read each resource's supported methods and scopes before making a request.

Examplehttp
POST /api/v1/validate
Authorization: Bearer YOUR_SCOPED_KEY
Content-Type: application/json

{
  "resource": "notes",
  "operation": "create",
  "data": {
    "title": "Draft for review",
    "content": "<p>Draft content.</p>",
    "group_id": "REPLACE_WITH_OWNED_GROUP_ID",
    "status": "draft",
    "sync_generated_site": false
  }
}

This endpoint supports Notes and Carousels payload validation. Inspect valid, errors, checks and not_checked in the response. It does not save content, verify group ownership, check revision freshness or prove that publication will work. Authentication may update the key usage timestamp.

For other resources, use only the validation or dry-run operations listed by their guide. If none is available, report that limit. There is no general API for running the application's internal test suite, and no CLI is required.

Shared request boundary (local hardening)

The central API now enforces explicit HTTP methods for covered central versioned routes. Unsupported methods return 405, an Allow header, and error_code=method_not_allowed. Nonempty mutation bodies must be JSON objects, with a maximum of 8 MiB and nesting below 64 levels. Invalid JSON returns 400; a supplied non-JSON media type returns 415. Existing raw Databoard patch arrays and multipart upload routes retain their separate contracts. Missing Content-Type and empty bodies remain compatibility exceptions; this does not validate resource fields.

API keys now require an active owning user as well as an active, unexpired key. A disabled or missing owner returns generic 401.

Discover one resource at a time:

Examplebash
curl --fail-with-body "$API_URL/help?view=operations&resource=notes"
curl --fail-with-body "$API_URL/help?view=operations&resource=carousels"

This public-safe catalog describes methods and observed scope tokens. It does not grant access, provide complete field schemas, or certify retries. Scope tokens may be alternatives or belong to different methods. Read the module reference before writing.

Transport errors have error_code and retryable=false; legacy domain errors are not all standardized yet. Do not rely on this envelope across every module. Unknown API paths can still produce a legacy error response.

Verify an API operation

Read the owned resource before editing. Use a documented validation or dry-run endpoint where available, perform the intended write, then read the result back. For generation, verify the mapping, deployment result and rendered output separately using the documented endpoints.

Do not deliberately probe another customer's records or trigger mail, billing or publication as a generic validation check. Negative tests belong in an operator-provided test environment with isolated fixtures.

Internal regression suites are maintained separately. Their results are not an API capability and do not certify your particular request.

Remaining hardening work

  • Extend the shared transport policy to Research Logging, Forms sync, and separately audited non-versioned surfaces.
  • Add consistent typed schemas and unknown-field rejection. Extracted body fields are not a substitute for validation.
  • Give Notes and other broad saves a revision contract. A fresh GET alone does not prevent concurrent overwrites.
  • Make compare-and-write atomic where a handler currently checks a hash and saves separately.
  • Extend the Carousel revision contract to legacy editor saves; agent updates already compare the persisted snapshot atomically and PATCH preserves omitted fields.
  • Define idempotency before automatically retrying external side effects.
  • Add scoped adapters for session-only modules instead of teaching agents to bypass their editors or databases.
  • Add an owned Docs chapter/collection writing API; the current agent Docs projection is read-only.
  • Review Labs isolation and durable storage before treating its shared machine-token interface as a multi-tenant service.

What to require from an implementation agent

Ask for the endpoint, exact credential and scope, owner rule, method, request schema, response schema, failure cases and side effects. Require negative tests against fixtures and a readback after a successful write. For generated websites, require source, mapping, generation and rendered behavior checks separately.

A validation endpoint should report what it checked and what remains untested. It must not return a generic readiness claim after checking only JSON syntax.

Guides for API-only agents

Start with GET /api/v1/help?view=guides. It lists 25 resource guides with API URLs. GET /api/v1/help?view=guide&resource=notes returns guidance, operation metadata and a guide revision; replace notes with a resource from the index. Modules without a direct versioned API explicitly say so. Do not invent browser endpoints to fill the gap.

GET /api/v1/help?view=schema&resource=notes and resource=carousels return enforced field schemas. Other resources return schema_not_available until implemented. POST /api/v1/validate is an authenticated, resource-scoped payload check for these two resources. It reports checks and not_checked explicitly; no content is saved, although authentication may update the key usage timestamp.

External agents need only HTTP access, the correct API origin, and a scoped key. Follow discovery → guide/schema → owned read → payload validation → write → readback. A valid payload is not proof of permission, revision freshness or successful publication.

Carousel updates now require expected_revision (428 missing, 409 stale) and use an atomic persisted-snapshot comparison. PATCH preserves omitted fields. Notes field validation is enforced, but Notes atomic revisions remain open.

API-only reader guide

See Use Antsand through HTTP for discovery, JSON guide fields, validation requests, revision handling and safe error recovery. The same resource guidance is available from GET /api/v1/help?view=guides; external agents do not need this repository.