API Overview

Our API provides access to business profiles that are optimized for AI agents and include machine-readable action schemas. All data is licensed under Creative Commons BY 4.0.

Base URL

https://privatehub.ai/api

Authentication

No authentication required for public endpoints

Rate Limits

100 requests per minute per IP

Endpoints

Business Actions API

Get detailed business information including available actions for AI agents.

GET /api/actions/{business-slug}

Retrieve business profile with available actions and API endpoints.

Parameters

business-slug (required) - The unique slug of the business

Response Example

{
  "business": {
    "id": 123,
    "name": "Pizza Palace",
    "url": "pizzapalace.com",
    "slug": "pizza-palace",
    "summary": "Best pizza in town",
    "contact": {
      "phone": "+1-555-1234",
      "email": "info@pizzapalace.com",
      "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      }
    },
    "actions": [
      {
        "type": "OrderAction",
        "api_endpoint": "https://pizzapalace.com/order",
        "method": "POST",
        "parameters": {
          "items": {
            "type": "array",
            "required": true
          },
          "address": {
            "type": "string",
            "required": true
          }
        },
        "documentation": "/api/docs/ordering",
        "platforms": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform"
        ]
      }
    ]
  },
  "api_info": {
    "version": "1.0",
    "documentation": "https://privatehub.ai/api-docs",
    "license": "CC BY 4.0",
    "generated_at": "2024-01-15T10:30:00Z"
  }
}

Action Types

🛒 OrderAction - Place orders for products/services

📅 ReserveAction - Make reservations or bookings

📧 ContactAction - Send messages or inquiries

📞 CallAction - Initiate phone calls

💰 BuyAction - Purchase products

📖 BookAction - Book services or appointments

📬 SubscribeAction - Subscribe to newsletters

⬇️ DownloadAction - Download files or resources

Business Profile API

Get basic business profile information.

GET /api/v1/profile/{business-slug}

Retrieve basic business profile information.

Business List API

Get a list of all published business profiles.

GET /api/v1/profiles

Retrieve a paginated list of all published business profiles.

Query Parameters

page (optional) - Page number (default: 1)
limit (optional) - Items per page (default: 20, max: 100)

JSON-LD Schema

All business profiles include structured JSON-LD data with Schema.org markup, including action schemas for AI agents.

Example Action Schema

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Pizza Palace",
  "url": "https://pizzapalace.com",
  "potentialAction": [
    {
      "@type": "OrderAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://pizzapalace.com/order",
        "actionPlatform": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform"
        ],
        "httpMethod": "POST",
        "contentType": "application/json"
      },
      "expects": {
        "@type": "Thing",
        "name": "OrderActionRequest",
        "properties": [
          {
            "name": "items",
            "type": "array"
          },
          {
            "name": "address",
            "type": "string"
          }
        ]
      }
    }
  ]
}

Error Handling

All API endpoints return appropriate HTTP status codes and error messages.

400 Bad Request

Invalid parameters or missing required fields

404 Not Found

Business profile not found or not published

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error, please try again later

API Documentation