API Ingestion Guide for AppEQ | AppEQ Help Center

This document outlines how to use our API to manage various business objects. It includes instructions on authentication, data ingestion, token expiration, error handling, and rate and size limits.

Base URL:
🔗 api1.appeq.ai

Authentication

Login Endpoint

To access the API, you need to log in and get a token.

URL: /auth/login
Method: POST

Request Body:

{
  "username": "your_username",
  "password": "your_password"
}

Response:

{
  "token": "your_token",
  "refresh_token": "your_refresh_token",
  "expires_in": 172800  // Token lasts for 2 days (172800 seconds)
}

Steps to Follow:

Send a POST request to /auth/login with your username and password.
You will receive a token and a refresh token in the response.
Use this token for authenticated requests to the API.

Refresh Token Endpoint

To keep using the API after your token expires, you need to refresh it.

URL: /auth/refresh
Method: POST

Request Body:

{
  "refresh_token": "your_refresh_token"
}

Response:

{
  "token": "your_new_token",
  "expires_in": 172800  // New token lasts for 2 days (172800 seconds)
}

Steps to Follow:

Send a POST request to /auth/refresh with your refresh token.
You will receive a new token in the response.
Use this new token for authenticated requests to the API.

Ingest Data for Business Object

Single Data Object

You can add a single data object to the API.

URL: /data/ingest
Method: POST
Headers: Authorization: Bearer {token}

Request Body:

{
  "object_type": "account",  // Type of data: "account", "order", "ticket"
  "primary_key": "account_id",  // Primary key field
  "data": {
    "account_id": "12345",
    "account_domain": "example.com",
    "additional_field_1": "value1",
    "additional_field_2": "value2"
  }
}

Response:

{
  "message": "Data ingested successfully",
  "code": 201,
  "created_columns": ["account_id", "account_domain", "additional_field_1", "additional_field_2"]
}

Steps to Follow:

Send a POST request to /data/ingest with the required headers and request body.
Include your token in the headers.
Include the type of data, primary key, and data object in the request body.
You will receive a confirmation message in the response.

Bulk Data

You can add multiple data objects at once.

URL: /data/ingest
Method: POST
Headers: Authorization: Bearer {token}

Request Body:

{
  "object_type": "orders",
  "primary_key": "orderId",
  "data": [
    {
      "account_id": "12345",
      "account_domain": "example.com",
      "orderId": "234567654",
      "additional_field_1": "value1",
      "additional_field_2": "value2"
    },
    {
      "account_id": "12345",
      "account_domain": "example.com",
      "orderId": "234567657",
      "additional_field_1": "value1",
      "additional_field_2": "value2"
    },
    {
      "account_id": "12346",
      "account_domain": "example1.com",
      "orderId": "234567655",
      "additional_field_1": "value1",
      "additional_field_2": "value2"
    }
  ]
}

Response:

{
  "message": "Data ingested successfully",
  "code": 201,
  "created_columns": ["account_id", "account_domain", "additional_field_1", "additional_field_2"]
}

Steps to Follow:

Send a POST request to /data/ingest with the required headers and request body.
Include your token in the headers.
Include the type of data, primary key, and an array of data objects in the request body.
You will receive a confirmation message in the response.

Token Expiration

Tokens are valid for 30 days (2592000000 seconds), this is configurable. After expiration, refresh the token using the /auth/refresh endpoint.

Steps to Follow:

Track the expiration time of your token.
Before the token expires, send a POST request to /auth/refresh with your refresh token to get a new token.
Use the new token for further API requests.

Error Handling

The API handles errors and provides detailed error responses.

Error Response Example:

{
  "error": "error_type",
  "message": "error_message",
  "status_code": status_code,
  "details": {}
}

Steps to Follow:

If an error occurs, check the error response from the API.
The response includes an error type, message, status code, and additional details.
Use this information to understand and resolve the issue.

Rate Limiting and Size Limiting

Rate Limiting

You can make 1 request per second with each API key.
If you exceed this limit, you'll get a 503 status code.

Steps to Follow:

Ensure your requests do not exceed 1 per second.
If you receive a 503 status code, slow down your requests.

Size Limiting

Request payloads can't exceed 1 MB.
For bulk data ingestion, you can send up to 500 objects.

Response for Exceeding Limits:

{
  "error": "PayloadTooLarge",
  "message": "Request payload exceeds the 1 MB limit.",
  "code": 413
}

Steps to Follow:

Ensure your request payloads are within the 1 MB limit.
For bulk data, ensure you are sending no more than 500 objects.
If you receive a 413 status code, reduce the size of your payload and try again.