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.

List once. Keep your audience on your site.

Giveaway City aggregates giveaways from independent publishers. Your API integration keeps your listing up to date and sends visitors to your entry page. You manage entries, payments, draws and prizes.

1. Get publisher credentials

Get your API key

Save the key when it is shown: only its hash is stored, so it cannot be retrieved later. Send it as Authorization: Bearer YOUR_API_KEY from your server.

You can rotate or revoke it in API Access. Rotation immediately disables the previous key. Your listings stay attached to your account, including after revocation and recreation.

Existing Portal.Service client-credentials tokens remain supported for service integrations with audience service.giveawaycity and scope giveawaycity:publish. Their listings use a separate namespace; switching to a user API key requires an explicit migration. service.connects does not issue these keys.

2. Publish a listing

Base URL: https://dev.portal.raum.au/giveawaycity. Include any deployment path prefix. Replace the placeholder host if this deployment has not configured its public URL.

POST /api/v1/giveaways creates or replaces your listing. Use your own stable giveaway ID. Repeating the request updates the same listing instead of creating a duplicate.

curl --request POST "$GIVEAWAY_CITY_BASE_URL/api/v1/giveaways" \
  --header "Authorization: Bearer $GIVEAWAY_CITY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
}'

All fields are strings. Requests are limited to 32 KB. Send a full listing on each update: omitted optional fields reset to their defaults.

Field	Required?	Format
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.

Success: HTTP 200 with { "listing": { ...publicFields, "status": "published", "updatedAt": "..." } }. Publisher ownership comes from your token. Listings start unverified; publishers cannot award themselves a trust badge.

3. Keep listings current

Send POST after publishing or editing. Read back your record with GET. Withdraw it when it closes, is cancelled or is deleted in your system.

# Read your listing (including withdrawn listings)
curl "$GIVEAWAY_CITY_BASE_URL/api/v1/giveaways?sourceExternalId=spring-giveaway-2027" \
  --header "Authorization: Bearer $GIVEAWAY_CITY_API_KEY"

# Withdraw; safe to repeat
curl --request DELETE "$GIVEAWAY_CITY_BASE_URL/api/v1/giveaways?sourceExternalId=spring-giveaway-2027" \
  --header "Authorization: Bearer $GIVEAWAY_CITY_API_KEY"

URL-encode the ID in query strings. DELETE returns HTTP 200 with the ID and status: withdrawn, even if already absent. POST with the same ID republishes it. GET returns 404 if this publisher has no matching record.

Use a durable queue and process each giveaway in order using its latest state. Reconcile periodically to repair missed updates. Public feed caches across instances can take up to 10 minutes to refresh.

Errors & retries

Error shape: { "error": { "message": "What to fix" } }.

400: fix the payload. 413: reduce it below 32 KB. 415: send application/json.
401: check whether your API key was rotated or revoked; update your server configuration. For Portal tokens, renew the token once. 403: check the required scope.
404 on GET: check the external ID and publisher client.
Network failures and 5xx: use bounded exponential retries with jitter. Respect 429 and Retry-After if your gateway returns them.

Existing integrations using /api/integrations/publish-giveaway keep their legacy payload format, with publisher ownership checks. Existing unowned records require operator ownership migration before updates; they return 409 until assigned. New integrations should use v1. Legacy listings are not automatically transferred to the new publisher namespace; arrange migration with the operator before backfilling them.

Browse giveaways