Gogenx Listings API

Getting started

Introduction

The Listings API lets you manage business listings programmatically. Every request and response is encoded as application/json.

Base URL https://gogenx.ai/api/v2

Application/JSON

Getting started

Authentication

All endpoints require an API key. Include your key in the apikey header on every request.

curl https://gogenx.ai/api/v2/businesses \
  -H "apikey: gxk_your_api_key_here"

Post /businesses

Create Business

Create a new business listing. Required fields: businessName, businessAddress, businessCity, businessState, businessZip and businessPhone. All other fields are optional.

Example request

curl -X POST https://gogenx.ai/api/v2/businesses \
  -H "apikey: gxk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "businessName": "Blue Sky Bakery",
  "businessAddress": "123 Main St",
  "businessAddress2": "Suite 4",
  "businessCity": "Austin",
  "businessState": "TX",
  "businessZip": "78701",
  "businessPhone": "+1-512-555-0142",
  "businessEmail": "hello@blueskybakery.com",
  "businessWebsite": "https://blueskybakery.com",
  "businessHours": { "MONDAY": "0700-1800", "SUNDAY": "closed" },
  "locationPin": { "lat": 30.2672, "lng": -97.7431 },
  "categories": [
    { "name": "Bakery", "isPrimary": true },
    { "name": "Coffee Shop", "isPrimary": false }
  ]
}'

Response · 201 Created

{
  "success": true,
  "submission": {
    "id": "sub_9f3a1b2c4d5e6f78",
    "businessName": "Blue Sky Bakery",
    "status": "queued",
    "submittedAt": "2026-04-23T16:42:03.512Z"
  }
}

Get /businesses

List Businesses

Retrieve a paginated list of your businesses. Supports page (default 1) and limit (default 20, max 100) query parameters.

Example request

curl "https://gogenx.ai/api/v2/businesses?page=1&limit=20" \
  -H "apikey: gxk_your_api_key_here"

Response · 200 OK

{
  "businesses": [
    {
      "id": 12,
      "gogenx_uuid": "gx_b8d2c91f4a7e4f3d",
      "name": "Blue Sky Bakery",
      "city": "Austin",
      "state": "TX",
      "subscription_tier": "free"
    },
    {
      "id": 15,
      "gogenx_uuid": "gx_2a7c16e9b0d34ac8",
      "name": "Northside Auto Repair",
      "city": "Portland",
      "state": "OR",
      "subscription_tier": "enhanced"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

Get /businesses/:id

Get Business

Fetch a single business by its gogenx_uuid.

Example request

curl https://gogenx.ai/api/v2/businesses/gx_b8d2c91f4a7e4f3d \
  -H "apikey: gxk_your_api_key_here"

Response · 200 OK

{
  "business": {
    "id": 12,
    "gogenx_uuid": "gx_b8d2c91f4a7e4f3d",
    "name": "Blue Sky Bakery",
    "address1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "phone": "+1-512-555-0142",
    "website_address": "https://blueskybakery.com",
    "primary_category": "Bakery",
    "subscription_tier": "free",
    "categories": [
      { "name": "Bakery", "isPrimary": true },
      { "name": "Coffee Shop", "isPrimary": false }
    ]
  }
}

Put /businesses/:id

Update Business

Update a business by its gogenx_uuid. The body accepts the same fields as Create Business. Provided fields overwrite existing values; omitted fields are unchanged.

Example request

curl -X PUT https://gogenx.ai/api/v2/businesses/gx_b8d2c91f4a7e4f3d \
  -H "apikey: gxk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "businessName": "Blue Sky Bakery & Cafe",
  "businessHours": { "MONDAY": "0700-1900", "SUNDAY": "0900-1500" }
}'

Response · 200 OK

{
  "success": true,
  "submission": {
    "id": "sub_4c7e2d81a9b6f035",
    "gogenxUuid": "gx_b8d2c91f4a7e4f3d",
    "businessName": "Blue Sky Bakery & Cafe",
    "status": "processed",
    "action": "updated",
    "submittedAt": "2026-04-23T17:05:22.884Z"
  }
}

Delete /businesses/:id

Deactivate Business

Deactivate a business by its gogenx_uuid. Deactivated listings stop appearing in public results, but their data is retained.

Example request

curl -X DELETE https://gogenx.ai/api/v2/businesses/gx_b8d2c91f4a7e4f3d \
  -H "apikey: gxk_your_api_key_here"

Response · 200 OK

{
  "success": true,
  "business": {
    "gogenxUuid": "gx_b8d2c91f4a7e4f3d",
    "status": "deactivated",
    "deactivatedAt": "2026-04-23T17:12:09.441Z"
  }
}

Reference

Schema Reference

The business object uses the following fields. Nested objects are shown where relevant.

Field	Type	Description
businessName Req	string	Legal or display name.
businessAddress Req	string	Street line 1.
businessAddress2	string	Street line 2.
businessCity Req	string	City.
businessState Req	string	Two-letter state code.
businessZip Req	string	Postal code.
businessPhone Req	string	E.164 format preferred.
businessEmail	string	Public contact email.
businessWebsite	string	Full URL including scheme.
businessHours	object	{ DAY: "HHMM-HHMM" \| "closed" } keyed by uppercase day.
locationPin	object	{ lat: number, lng: number }
doorPin	object	{ lat, lng } — entrance coordinates.
categories	array	[{ name, isPrimary }] — exactly one entry isPrimary: true.
media	array	[{ r2Key, type: "image" \| "video", description }]
prompts	array	[{ input, expectedOutput }] — LLM test prompts.
blogs	array	[{ title, author, body }]

Reference

Error Codes

Error responses share a consistent envelope with a machine-readable code and a human-readable message.

{
  "error": {
    "code": "MISSING_FIELDS",
    "message": "Business name, address, city, state, zip, and phone are required"
  }
}

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Internal Server Error

Gogenx Listings API

Introduction

Authentication

Create Business

List Businesses

Get Business

Update Business

Deactivate Business

Schema Reference

Error Codes

Ready to get discovered?