REST API for hire-yard operations.

Quickstart

1. 1. Sign in. The API uses the same Cognito user pool as the web app. Sign in via the /counter/ flow and pull the JWT from your session, or use the AWS Cognito SDK directly with InitiateAuth.
2. 2. Pick the right base URL. Tenants are region-pinned at signup based on the email TLD (.com.au → ap-southeast-2, .co.nz → ap-southeast-6, .co.uk → eu-west-2, etc.). Use the base URL for your region — cross-region requests work but add latency.
3. 3. Send the JWT in the Authorization header. Authorization: Bearer <id_token>. The token's custom claims (tenantId, role, homeRegion) gate access to every endpoint automatically.

# Example: list your assets (curl)

curl https://api-syd.yardguild.com/assets \
  -H "Authorization: Bearer $YG_TOKEN"

# Example: seed your starter library
curl -X POST https://api-syd.yardguild.com/assets/seed \
  -H "Authorization: Bearer $YG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vertical":"tools","country":"AU"}'

# Example: create a contract
curl -X POST https://api-syd.yardguild.com/contracts \
  -H "Authorization: Bearer $YG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "renter": {"name":"Acme Builders", "email":"j@acme.com.au"},
    "items": [{"asset_id":"abc-123","daily_rate":70}],
    "due_back_at": "2026-06-02T17:00:00+10:00"
  }'

Base URLs (per region)

Tenants are region-pinned. Your home region is in the custom:homeRegion claim of your JWT.

Custom-domain mappings ship after the first paying tenant in each region. Until then, use the raw API Gateway URL from /counter/settings.

Conventions

• JSON in, JSON out. Send Content-Type: application/json on POST / PUT / PATCH. Errors return { "code": "...", "message": "..." }. Exceptions: CSV endpoints return text/csv, presign endpoints return the upload URL.
• Tenant isolation by construction. Every endpoint scopes by the custom:tenantId claim. You cannot read another tenant's data — even a misformed query falls back to your tenant.
• Errors are predictable. 401 missing/invalid JWT · 403 role insufficient · 404 resource not found · 409 conflict (e.g. illegal state transition) · 422 validation error (per-field details in errors[]) · 429 rate-limited · 5xx server error (retry with backoff).
• Rate limit: 50 req/sec per tenant. Burst of 100. Hits return 429 with Retry-After header. Email us if you need more — usually we'll just raise it.
• Idempotency. POST endpoints accept an optional Idempotency-Key header; we deduplicate for 24 hours. The PayPal webhook ingestion is idempotent by design (event ID stored in DDB for 90-day TTL).
• No payment processing on renters. The Bonds endpoints record payment details (method / reference / ID-sighted / photos) but never charge anything. The money flow stays with your existing processor — cash, EFTPOS, Square, your own PayPal Business or Stripe, etc. The only place YardGuild processes a payment is your monthly Pro-tier subscription via /billing/subscribe.

Endpoints

All endpoints require a Cognito JWT in the Authorization header unless otherwise noted. The handful of public endpoints (waiver renter flow, PayPal webhook, health) carry their own auth mechanism (token, signature, or none).

Webhooks

We receive PayPal subscription webhooks at /webhooks/paypal (signature-verified, idempotent — see Bonds note about event-ID-keyed DDB rows with 90-day TTL).

Outbound webhooks (notify your system on contract state changes, bond captures, etc.) are on the roadmap. Email us if this is the integration you need — we'll prioritise it.