API access

Automatically list giveaways from your website.

Sign in to create your API key

Use Log In or Sign Up in the navigation, then return to this page. No operator provisioning is required.

Read the API documentation

Giveaway City API documentation

Integrate with one copy pasted ai prompt

Copy this prompt into your AI coding assistant inside your project. It includes authentication, the full API contract, automatic updates and withdrawal.

You will need publisher credentials to connect your finished integration.

Complete integration prompt

Integrate this project's giveaways with Giveaway City's aggregator API. Inspect the existing framework, giveaway model and background job system, then implement the integration end to end using existing conventions.

Giveaway City lists giveaways and sends visitors to our website. Keep entry collection, payments, social verification, draws and prize delivery in our existing system.

Configuration (server-side secrets only):
- GIVEAWAY_CITY_BASE_URL=https://dev.portal.raum.au/giveawaycity
- GIVEAWAY_CITY_API_KEY=<create in Giveaway City /api-access while signed in>
Never put the key in browser code, NEXT_PUBLIC variables, source control, logs or this AI conversation. Add placeholders to an environment example. If missing, finish the implementation and identify required deployment configuration; do not invent a key or claim live integration succeeded.

Authentication:
Send Authorization: Bearer <GIVEAWAY_CITY_API_KEY> on every API call. This is a long-lived Giveaway City publishing key; no token exchange is needed. The full key is shown once when created or rotated. On 401 stop retries and ask the operator to check whether the key was rotated or revoked. Never try to create keys programmatically using browser cookies.

API contract (append paths to the configured base URL, preserving any deployment prefix):
POST /api/v1/giveaways with Content-Type: application/json. Publishes or fully replaces one listing. All fields are strings. Maximum body: 32 KB.
sourceExternalId: Required. Your stable giveaway ID. Up to 200 characters. Reuse it for every update.
title: Required. Public title, up to 160 characters.
description: Required. Up to 4,000 characters. Include entry costs, eligibility and important conditions.
landingUrl: Required. Absolute HTTP(S) URL of your entry page, up to 2,048 characters.
provider: Optional. Public organizer name, up to 120 characters. Defaults to Independent publisher.
image: Optional. Public absolute HTTP(S) image URL, up to 2,048 characters.
platform: Optional. Platform identifier, up to 80 characters; e.g. steam, pc, or all (default).
worth: Optional. Display value, up to 40 characters; e.g. $100 AUD. Defaults to N/A.
instructions: Optional. How to enter, up to 4,000 characters. Defaults to a link-out instruction.
endDate: Optional. UTC ISO timestamp including seconds and Z; e.g. 2027-04-30T20:00:00Z. Defaults to N/A.

Example request:
{
  "sourceExternalId": "spring-giveaway-2027",
  "title": "Win a gaming gift card",
  "description": "Enter on our website. See the official page for entry requirements, eligibility and full terms.",
  "landingUrl": "https://example.com/giveaways/spring-2027",
  "provider": "Example Gaming",
  "image": "https://example.com/images/spring-giveaway.jpg",
  "endDate": "2027-04-30T20:00:00Z"
}

200 response: { "listing": { ...public fields above, "status": "published", "updatedAt": "<ISO timestamp>" } }.
GET /api/v1/giveaways?sourceExternalId=<URL-encoded ID> returns the same shape, including withdrawn records, or 404.
DELETE /api/v1/giveaways?sourceExternalId=<URL-encoded ID> withdraws a listing; returns 200 { "sourceExternalId": "...", "status": "withdrawn" }, even if already absent. A subsequent POST republishes it.
Error response: { "error": { "message": "..." } }. Statuses: 400 invalid input, 401 invalid/expired token, 403 missing scope, 404 missing listing on GET, 413 body too large, 415 wrong content type, 503 unavailable. Respect 429 and Retry-After if returned by the gateway.

Ownership is derived from the authenticated publisher. Never send a source, sourceTenant, verifiedStatus, actions, entries, gift codes, customer data or payment data. Different publishers may reuse the same external ID. Keys belong to the signed-in account; rotation and recreation preserve listing ownership. API keys and legacy Portal service clients have separate namespaces; existing service-client listings require an explicit migration.

Implementation requirements:
1. Map our stable giveaway ID and public fields; send a complete payload on every publish/update because omitted optional fields reset to defaults. Preserve the exact closing instant by converting it to UTC. Clearly describe paid-entry conditions where applicable.
2. Enqueue a sync after our giveaway is published or edited. Withdraw on cancellation, deletion or closing. Backfill existing public giveaways through a deliberate admin command, not automatically on deployment.
3. Use durable jobs, bounded timeouts and capped exponential retries with jitter for network failures, 429 and 5xx. Reuse the same ID on retries. Serialize/coalesce jobs per giveaway, loading its latest state so stale retries cannot republish a withdrawn listing. Treat validation errors as actionable failures.
4. Save sync status, last successful sync time and safe error messages locally. Add a reconciliation job that checks and repairs missed updates. Public feed caches can take up to 10 minutes to refresh; an API success does not guarantee immediate appearance on every instance.
5. Test publish/update without duplicates, isolation between publishers, revoked-key handling, validation failures, retries, withdrawal and republishing using mocks or an isolated test database. Never publish a real giveaway as a test without explicit authorization.
6. Provide setup instructions and summarize changed files, checks run and any configuration still needed. Implement working code rather than only a plan.