openapi: 3.0.3
info:
  title: Hoox AI CMO Public API
  version: 1.0.0
  description: Public read-only API and agent discovery interface for Hoox — the autonomous
    AI Chief Marketing Officer deploying 6 specialized agents for SEO/GEO blogs, TikTok/Instagram
    carousels, YouTube videos, LinkedIn/Facebook posts, Reddit community engagement,
    and X intent replies.
  contact:
    name: Hoox Support
    url: https://tryhoox.com/contact
    email: support@tryhoox.com
  license:
    name: Proprietary
    url: https://tryhoox.com/legal/terms
servers:
- url: https://tryhoox.com
  description: Production Server
paths:
  /api/v1/status:
    get:
      operationId: getApiStatus
      summary: Check API and Service Health
      description: Returns operational health status of the Hoox platform, version
        information, and canonical links to documentation, openapi specification,
        and llms.txt.
      responses:
        '200':
          description: Service is healthy and reachable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiStatusResponse'
        '404': &id001
          description: Resource not found or client error
          content:
            application/json:
              schema:
                ? ''
                : '#/components/schemas/ApiError'
      security:
      - OAuth2:
        - read:status
      - BearerAuth: []
      - {}
  /api/v1/agents:
    get:
      operationId: listMarketingAgents
      summary: List Autonomous Marketing Agents
      description: Returns the complete roster of 6 specialized autonomous marketing
        agents deployed by Hoox, including their target channels, capabilities, cadence,
        and output formats.
      responses:
        '200':
          description: Successfully retrieved list of marketing agents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsListResponse'
        '404': *id001
      security:
      - OAuth2:
        - read:agents
      - BearerAuth: []
      - {}
  /api/v1/pricing:
    get:
      operationId: getPricingPlans
      summary: Get Pricing and Credit Allocation
      description: Retrieves the public pricing structure of Hoox, including the $99.00
        USD / 28-day base subscription, included 10,000 credits, $0.0099 overage rate,
        and credit usage per agent task.
      responses:
        '200':
          description: Successfully retrieved pricing structure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricingResponse'
        '404': *id001
      security:
      - OAuth2:
        - read:pricing
      - BearerAuth: []
      - {}
  /api/v1/info:
    get:
      operationId: getCompanyInfo
      summary: Get Company Profile and Brand Information
      description: Returns verified brand and corporate entity information for Hoox,
        including headquarters location in Tel Aviv, legal entity, official social
        media links, and trust anchors.
      responses:
        '200':
          description: Successfully retrieved company profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyInfoResponse'
        '404': *id001
      security:
      - OAuth2:
        - read:info
      - BearerAuth: []
      - {}
  /api/v1/contact:
    get:
      operationId: getContactInfo
      summary: Get Support and Inquiry Information
      description: Returns contact channels, support email (support@tryhoox.com),
        phone number, office location, and business hours for human inquiries and
        AI agent referrals.
      responses:
        '200':
          description: Successfully retrieved contact details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactInfoResponse'
        '404': *id001
      security:
      - OAuth2:
        - read:contact
      - BearerAuth: []
      - {}
components:
  schemas:
    ApiStatusResponse:
      type: object
      required:
      - status
      - version
      - service
      - documentation_url
      - openapi_url
      - llms_url
      - endpoints
      properties:
        status:
          type: string
          example: healthy
          description: Current platform health status.
        version:
          type: string
          example: 1.0.0
          description: API semantic version.
        service:
          type: string
          example: Hoox AI CMO Public API
          description: Service name.
        description:
          type: string
          example: Autonomous AI Chief Marketing Officer multi-channel orchestration
            API
          description: Summary of service capability.
        timestamp:
          type: string
          format: date-time
          example: '2026-09-10T00:00:00Z'
          description: Status timestamp.
        documentation_url:
          type: string
          format: uri
          example: https://tryhoox.com/docs
          description: URL to developer documentation.
        openapi_url:
          type: string
          format: uri
          example: https://tryhoox.com/openapi.json
          description: URL to OpenAPI specification.
        llms_url:
          type: string
          format: uri
          example: https://tryhoox.com/llms.txt
          description: URL to machine-readable LLM instructions.
        endpoints:
          type: object
          description: Key API endpoints map.
          additionalProperties:
            type: string
            format: uri
    MarketingAgent:
      type: object
      required:
      - id
      - name
      - channel
      - description
      - integrations
      - output_format
      - cadence
      properties:
        id:
          type: string
          example: seo_geo
          description: Unique agent identifier.
        name:
          type: string
          example: SEO & GEO Long-Form Blog Agent
          description: Human-readable agent name.
        channel:
          type: string
          example: Website & Search Engines
          description: Target publishing destination.
        description:
          type: string
          example: Performs keyword gap research, builds programmatic search clusters,
            and writes authoritative 1,500+ word articles optimized for Google Search
            and Generative AI engines.
          description: Detailed explanation of autonomous functionality.
        integrations:
          type: array
          items:
            type: string
          example:
          - WordPress
          - Shopify
          - Webflow
          - Custom Webhooks
          description: Supported channel integrations.
        output_format:
          type: string
          example: Markdown / HTML with schema markup
          description: Asset deliverable format.
        cadence:
          type: string
          example: Scheduled daily or weekly
          description: Publishing execution rhythm.
    AgentsListResponse:
      type: object
      required:
      - service
      - version
      - total_agents
      - agents
      properties:
        service:
          type: string
          example: Hoox AI CMO
          description: Platform name.
        version:
          type: string
          example: 1.0.0
          description: Version.
        total_agents:
          type: integer
          example: 6
          description: Total count of autonomous agents in the platform.
        description:
          type: string
          example: Six autonomous marketing agents operating 24/7 on autopilot to
            drive compounding organic traffic.
        agents:
          type: array
          items:
            $ref: '#/components/schemas/MarketingAgent'
    PricingResponse:
      type: object
      required:
      - service
      - currency
      - pricing_model
      - base_plan
      - pricing_page_url
      properties:
        service:
          type: string
          example: Hoox AI CMO
        currency:
          type: string
          example: USD
        pricing_model:
          type: string
          example: Subscription + Usage Credits
        base_plan:
          type: object
          required:
          - name
          - price
          - billing_period_days
          - included_credits
          - overage_rate_per_credit
          - features
          properties:
            name:
              type: string
              example: Base Plan
            price:
              type: number
              example: 99.0
            billing_period_days:
              type: integer
              example: 28
            included_credits:
              type: integer
              example: 10000
            overage_rate_per_credit:
              type: number
              example: 0.0099
            features:
              type: array
              items:
                type: string
        credit_usage_estimates:
          type: object
          description: Credit costs for typical agent tasks.
        pricing_page_url:
          type: string
          format: uri
          example: https://tryhoox.com/pricing
    CompanyInfoResponse:
      type: object
      required:
      - name
      - legal_name
      - url
      - description
      - founding_year
      - headquarters
      - contact
      - social_profiles
      properties:
        name:
          type: string
          example: Hoox
        legal_name:
          type: string
          example: Idan Barel doing business as Hoox
        alternate_names:
          type: array
          items:
            type: string
          example:
          - Hoox AI
          - Hoox CMO
          - Hoox AI CMO
          - TryHoox
        url:
          type: string
          format: uri
          example: https://tryhoox.com
        description:
          type: string
        founding_year:
          type: integer
          example: 2024
        headquarters:
          type: object
          required:
          - street
          - city
          - postal_code
          - country
          - country_code
          properties:
            street:
              type: string
              example: HaArba'a Street, 28
            city:
              type: string
              example: Tel Aviv-Yafo
            postal_code:
              type: string
              example: '6473925'
            country:
              type: string
              example: Israel
            country_code:
              type: string
              example: IL
        contact:
          type: object
          required:
          - support_email
          - telephone
          properties:
            support_email:
              type: string
              format: email
              example: support@tryhoox.com
            telephone:
              type: string
              example: +972-3-555-0100
        social_profiles:
          type: object
          properties:
            instagram:
              type: string
              format: uri
            facebook:
              type: string
              format: uri
            linkedin:
              type: string
              format: uri
            x:
              type: string
              format: uri
        trust_pages:
          type: object
          additionalProperties:
            type: string
            format: uri
    ContactInfoResponse:
      type: object
      required:
      - service
      - support_email
      - telephone
      - office_location
      - business_hours
      properties:
        service:
          type: string
          example: Hoox Support & Contact
        support_email:
          type: string
          format: email
          example: support@tryhoox.com
        telephone:
          type: string
          example: +972-3-555-0100
        office_location:
          type: object
          properties:
            organization:
              type: string
              example: Hoox
            street:
              type: string
              example: HaArba'a Street, 28
            city:
              type: string
              example: Tel Aviv-Yafo
            postal_code:
              type: string
              example: '6473925'
            country:
              type: string
              example: Israel
        business_hours:
          type: object
          properties:
            days:
              type: string
              example: Sunday - Thursday
            hours:
              type: string
              example: 09:00 - 18:00 IST (UTC+3)
            system_status:
              type: string
              example: Automated AI marketing agents run 24/7/365 on continuous autopilot
        inquiries:
          type: object
          additionalProperties:
            type: string
        web_contact_page:
          type: string
          format: uri
          example: https://tryhoox.com/contact
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - status
          - resolution_hint
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: The requested API resource was not found.
            status:
              type: integer
              example: 404
            resolution_hint:
              type: string
              example: Verify the endpoint path. Use GET /api/v1/status to discover
                available endpoints or consult https://tryhoox.com/openapi.json.
            documentation_url:
              type: string
              format: uri
              example: https://tryhoox.com/docs
            openapi_url:
              type: string
              format: uri
              example: https://tryhoox.com/openapi.json
            available_endpoints:
              type: array
              items:
                type: string
              example:
              - https://tryhoox.com/api/v1/status
              - https://tryhoox.com/api/v1/agents
              - https://tryhoox.com/api/v1/pricing
              - https://tryhoox.com/api/v1/info
              - https://tryhoox.com/api/v1/contact
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authorization with scoped permissions for autonomous
        AI agents and developer integrations (RFC 6749 & RFC 9728)
      flows:
        authorizationCode:
          authorizationUrl: https://tryhoox.com/oauth/authorize
          tokenUrl: https://tryhoox.com/oauth/token
          scopes: &id002
            read:status: Read platform operational status, service health, and API
              metadata
            read:agents: Inspect roster, capabilities, and configurations of the 6
              autonomous marketing agents
            read:pricing: Retrieve subscription pricing, credit allocations, and task
              overage rates
            read:info: Access verified company profile, legal entity, headquarters,
              and trust anchors
            read:contact: Access support channels, inquiry emails, and phone contacts
            read:docs: Access developer API documentation and schema specifications
            write:agents: Configure, schedule, or trigger autonomous marketing agent
              tasks
            write:campaigns: Create, update, or approve marketing campaigns and content
              drafts
            write:integrations: Connect or configure CMS and social media publishing
              channels
        clientCredentials:
          tokenUrl: https://tryhoox.com/oauth/token
          scopes: *id002
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token carrying granted OAuth scopes in claims
security:
- OAuth2:
  - read:status
- BearerAuth: []
- {}