{ "openapi": "3.1.0", "info": { "title": "OZFINDA Agent API", "version": "1.0.0", "description": "Search Australia's business directory and create or maintain listings for Australian businesses. Read the playbook first: https://ozfinda.com.au/docs/agents", "contact": { "url": "https://ozfinda.com.au/contact" } }, "servers": [ { "url": "https://ozfinda.com.au/api/v1" } ], "externalDocs": { "url": "https://ozfinda.com.au/docs/agents", "description": "Agent Playbook" }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API key: ozf_..." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "code", "docs_url" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "conflict", "content_policy", "quota_exceeded", "rate_limited", "method_not_allowed", "payload_too_large" ] }, "field": { "type": "string" }, "docs_url": { "type": "string" } } }, "ListingInput": { "type": "object", "additionalProperties": false, "properties": { "business_name": { "type": "string", "minLength": 2, "maxLength": 120 }, "username": { "type": "string", "minLength": 3, "maxLength": 32, "pattern": "^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$" }, "category": { "type": "string", "description": "Single category slug (alternative to categories)." }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "accommodation", "accountant", "advertising", "arts-culture", "automotive", "baby-goods", "beauty", "boats", "books", "business-services", "business-opportunity", "cars", "charities", "childrens-goods", "classifieds", "cleaning", "computers", "corporate", "credit-management", "debt-collectors", "dental", "directories", "domain-names", "education", "electrical", "engineering", "entertainment", "events", "fashion", "festivals", "finance", "food-wine", "furniture", "gardening", "giftware", "graphic-designers", "hardware", "health", "holidays", "home-design", "home-improvement", "homewares", "hosting", "insurance", "internet", "jewellers", "jobs", "legal", "lifestyle", "logistics", "manufacturers", "marketing", "media", "motorcycles", "music", "news", "online-shopping", "pest-management", "pets", "photography", "real-estate", "restaurants", "security", "self-storage", "services", "shopping", "software", "sports", "supplier", "telecommunications", "trades", "training", "web-design", "weddings", "wholesalers", "windows", "other" ] }, "minItems": 1, "maxItems": 10 }, "tagline": { "type": [ "string", "null" ], "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "phone": { "type": [ "string", "null" ], "maxLength": 32 }, "email": { "type": [ "string", "null" ], "format": "email" }, "website": { "type": [ "string", "null" ], "format": "uri", "description": "One listing per website across the directory." }, "address": { "type": [ "string", "null" ], "maxLength": 200 }, "suburb": { "type": [ "string", "null" ], "maxLength": 80 }, "state": { "type": "string", "description": "Australian state/territory code or full name.", "examples": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT" ] }, "postcode": { "type": [ "string", "null" ], "pattern": "^\\d{4}$" }, "service_area": { "type": [ "string", "null" ], "maxLength": 200 }, "highlights": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "maxItems": 8 }, "published": { "type": "boolean", "default": true } } }, "Listing": { "type": "object", "properties": { "business_name": { "type": "string", "minLength": 2, "maxLength": 120 }, "username": { "type": "string", "minLength": 3, "maxLength": 32, "pattern": "^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$" }, "category": { "type": "string", "description": "Single category slug (alternative to categories)." }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "accommodation", "accountant", "advertising", "arts-culture", "automotive", "baby-goods", "beauty", "boats", "books", "business-services", "business-opportunity", "cars", "charities", "childrens-goods", "classifieds", "cleaning", "computers", "corporate", "credit-management", "debt-collectors", "dental", "directories", "domain-names", "education", "electrical", "engineering", "entertainment", "events", "fashion", "festivals", "finance", "food-wine", "furniture", "gardening", "giftware", "graphic-designers", "hardware", "health", "holidays", "home-design", "home-improvement", "homewares", "hosting", "insurance", "internet", "jewellers", "jobs", "legal", "lifestyle", "logistics", "manufacturers", "marketing", "media", "motorcycles", "music", "news", "online-shopping", "pest-management", "pets", "photography", "real-estate", "restaurants", "security", "self-storage", "services", "shopping", "software", "sports", "supplier", "telecommunications", "trades", "training", "web-design", "weddings", "wholesalers", "windows", "other" ] }, "minItems": 1, "maxItems": 10 }, "tagline": { "type": [ "string", "null" ], "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "phone": { "type": [ "string", "null" ], "maxLength": 32 }, "email": { "type": [ "string", "null" ], "format": "email" }, "website": { "type": [ "string", "null" ], "format": "uri", "description": "One listing per website across the directory." }, "address": { "type": [ "string", "null" ], "maxLength": 200 }, "suburb": { "type": [ "string", "null" ], "maxLength": 80 }, "state": { "type": "string", "description": "Australian state/territory code or full name.", "examples": [ "NSW", "VIC", "QLD", "WA", "SA", "TAS", "ACT", "NT" ] }, "postcode": { "type": [ "string", "null" ], "pattern": "^\\d{4}$" }, "service_area": { "type": [ "string", "null" ], "maxLength": 200 }, "highlights": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "maxItems": 8 }, "published": { "type": "boolean", "default": true }, "url": { "type": "string" }, "id": { "type": "string", "description": "Owner view only." }, "status": { "type": "string", "enum": [ "live", "draft", "pending_review", "rejected" ], "description": "Owner view only." }, "moderation": { "type": "object", "properties": { "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] } } }, "dashboard_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ListingResult": { "type": "object", "properties": { "listing": { "$ref": "#/components/schemas/Listing" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "verify_email", "publish", "await_review" ] }, "detail": { "type": "string" } } } } } } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/agents/register": { "post": { "summary": "Create an account and its first API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "key_name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Account + api_key.key (shown once)" }, "400": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/api-keys": { "get": { "summary": "List live keys", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "api_keys[]" }, "401": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Mint a key (Bearer key, or email + password)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" } } } } } }, "responses": { "201": { "description": "api_key.key (shown once)" }, "401": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/api-keys/{id}": { "delete": { "summary": "Revoke a key", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/me": { "get": { "summary": "Account, plan quota and listings", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "account, plan, listings[]" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/categories": { "get": { "summary": "Category slugs", "responses": { "200": { "description": "categories[]" } } } }, "/listings": { "get": { "summary": "Search live listings", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "results[], next_offset" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Create a listing (moderated)", "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListingInput" }, { "required": [ "business_name", "state" ] } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/listings/{username}": { "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get a listing (owner sees drafts + status)", "responses": { "200": { "description": "listing" }, "404": { "$ref": "#/components/responses/Error" } } }, "patch": { "summary": "Update fields or publish/unpublish", "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingInput" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "summary": "Delete a listing permanently", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } } } }