Skip to main content

ai12z REST API Documentation

Welcome to the ai12z REST API, providing developers with access to a suite of AI-powered tools and services. This document outlines the available endpoints, request methods, and expected payloads to help you integrate your applications seamlessly with our platform.

Base URL​

All API requests should be made to the base URL: https://api.ai12z.net/

Content-Type​

All requests should include the Content-Type: application/json header.

Authentication​

Some endpoints require an API key for authentication. Include your API key in the request payload where required.

Endpoints​

Health Check​

  • Endpoint: /api/healthz
  • Method: POST, GET
  • Description: Checks the API's health and returns a status message.
  • Request Body: None
  • Responses:
    • 200 OK
      • application/json
      • Example: {"status": "ok"}

Search Documents Metadata​

  • Endpoint: /api/search
  • Method: POST
  • Description: Retrieves metadata for documents based on the specified search parameters.
  • Request Body:
    • apiKey (Required for authenticated requests): API key for authentication, and for Analytics.
    • numDocs (Required): Number of documents to retrieve.
    • query (Required): Search query.
    • score (Optional): Relevancy score 0 - .99 higher the value the more relevant the answer needs to be
    • includeTags (Optional): Array of tags, only content with one of these tags will be returned
    • excludeTags (Optional): Array of tags, content will be excluded if it has one of these tags
    • returnContent (Optional): true or false, default is false. This could be used as a way to retrieve documents if you wanted your own RAG with another LLM, using ai12z as the repository.
  • Responses:
    • 200 OK
      • application/json
      • Example: [{"title": title,"description": description,"link": url,"assetType": 'web'}]

Ask AI​

  • Endpoint: /api/askai
  • Method: POST
  • Description: Submits a query to the AI and retrieves an answer.
  • Request Body:
    • query "What is ai12z address?"
    • format The format of the response (html or markdown).
    • conversationId ID to track conversation context, use the id from the last response, this is used for it understanding history or return empty string, if fist response, or if you do not want to continue the conversation related to previous questions
    • meta (Optional) Dictionary that includes title, origin (URL question is coming from), language, referrer(previous url, where user came from)
    • attributes (Optional) developer can pass a dictionary of additional data that can be used in prompts if you include the attributes tag. For example personalization info from a CMS system
    • base64Images (Optional) Array of images ['"data:image/png;base64,iVBORw0K...','"data:image/png;base64,iVC7Rw0K...']
    • apiKey (Required for authenticated requests): API key for authentication.
    • includeTags (Optional): Array of tags, only content with one of these tags will be returned
    • excludeTags (Optional): Array of tags, content will be excluded if it has one of these tags
  • Responses:
    • 200 OK - application/json - Example: data = { "answer": "ai12z's office is located at 867 Boylston Street, 5th Floor 1011, Boston, Massachusetts 02116.", "title": "Contacting ai12z", "link": "https://docs.ai12z.net/docs/privacy-security/", "description": "Some short description", "relevanceScore": 98.8, "assetType": "web", "didAnswer": true, "context": dict_contexts, "insightId": "66d8ab6334a418a0d4a03d9d", "error": None, "conversationId": "66d8ab6334a418a0d4a03d9c", }

JSON response following a POST request. The structure shows nested JSON objects with key-value pairs, representing various data points such as a request id, agent id, and query. The response contains detailed text information including descriptions, metadata, and URLs, suggesting it might be related to a search or query operation within a digital assistant or search functionality. The nature of the content suggests it is part of a backend service processing information requests

Submit Feedback​

  • Endpoint: /api/feedback
  • Method: POST
  • Description: Submits feedback on insights provided by the AI.
  • Request Body:
    • insightId (Required): The ID of the insight.
    • feedback (Required): Feedback value (either 1 for positive or -1 for negative).
  • Responses:
    • 200 OK
      • application/json
      • Example: {"success": true}

Error Handling​

The ai12z API uses standard HTTP response codes to indicate the success or failure of an API request. In general:

  • 2xx codes indicate success.
  • 4xx codes indicate an error resulting from the provided information (e.g., a required parameter was omitted).
  • 5xx codes indicate an error with ai12z's servers.

Error responses will include additional information about the error in the response body.