API Documentation

Introduction

Welcome to the agri1.ai API, your gateway to leverage the power of our continuously evolving, agriculture-specific large language model. At present, this API version supports chat-based interactions with agri1's agronomic AI advisor. However, the capabilities of agri1's AI are set to expand beyond chat in the future.

Join us in shaping the future of agricultural conversations by leveraging the cutting-edge capabilities of the agri1.ai API.

Security & CORS

During the BETA phase of our API, Cross-Origin Resource Sharing (CORS) is not supported. This means that client-side requests from web browsers to our API will be restricted to prevent cross-origin issues. However, we fully support server-side requests. This allows developers to integrate our API into their server-side applications and services without facing the limitations imposed by CORS.

We recommend implementing any required interactions with our API through server-side logic during this phase, ensuring seamless functionality and security.

Authorization

This API secures its endpoints through Bearer Authentication, requiring an auth-token for all operations. The auth-token should be included in the Authorization header of each request. This section outlines how to obtain and use your auth-token.

During the BETA phase, self-management of auth-tokens is not available. However, once we transition to production, you will gain the capability to log in and manage your auth-tokens independently. In the meantime, if you're interested in becoming a BETA tester, please reach out to us for further details.

Using Your auth-token

Example of an API Call with Bearer Token

curl -X GET 'https://api.agri1.ai/api/v1/me' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN'

GET /api/v1/me HTTP/1.1
Host: api-staging.agri1.ai
Authorization: Bearer YOUR_AUTH_TOKEN

Once you have your auth-token, include it in the HTTP Authorization header as a Bearer token in all API requests. Here is the general format of the Authorization header:

Errors Related to Authentication

If you encounter errors related to authentication, here are some common issues and their meanings:

Rate Limiting

Please note that the API is subject to rate limiting to ensure fair usage. If you exceed the rate limit, you will receive a 429 Too Many Requests response.

For details about specific limits please contact us via e-mail info@agri1.ai.

User

This endpoint returns information about the current user based on the provided auth-token. It does not allow the creation of custom users on your behalf. This endpoint is read-only and provides information about yourself.

GET /api/v1/me

Example Request GET /api/v1/me

curl -X GET 'https://api.agri1.ai/api/v1/me' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN'

GET /api/v1/me HTTP/1.1
Authorization: Bearer YOUR_AUTH_TOKEN

Response

{
  "description": "Just a test api-key",
  "user": {
      "email": "your@mailadress.com"
  }
}

It shows information about yourself as a requester. This includes the connected api token's email address. You can use this to make sure your token is valid and is connected to your e-mail address.

Request Headers

Request Params

None. This endpoint does not require any query parameters.

Response

Chats

Chats, sometimes also known as threads, are objects designed to hold a complete conversation on a specific topic. A chat can contain multiple messages, which are often formulated as questions. It also contains multiple responses to these messages, which serve as answers provided by agri1.ai.

POST /api/v1/chats

Example Request POST /api/v1/chats

curl -X POST 'https://api.agri1.ai/api/v1/chats' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
      "chat": {
          "name": "First Chat Thread"
      }
}'

POST /api/v1/chats HTTP/1.1
Authorization: Bearer YOUR_AUTH_TOKEN
{
    "chat": {
        "name": "First Chat Thread"
    }
}

Response

{
    "id": "e3f246ed-7dce-4d22-9bc9-c50dc52d64e5",
    "name": "First Chat Thread",
    "created_at": "2024-02-21T09:49:57.185Z"
}

To begin, you must start a new conversation by creating a new chat, also commonly referred to as a thread. To create a chat, only an optional name is required. Simply assign a name to your new chat for easier identification later on. Upon creation, the response will include the chat_id, which is necessary for sending new messages to initiate your conversation.

Request Headers

Request Params

Response

Errors

If you encounter errors, here are some common issues and their meanings:

GET /api/v1/chats/:id

Example Request GET /api/v1/chats

curl -X GET 'https://api.agri1.ai/api/v1/chats/:id' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN'

GET /api/v1/chats/:id HTTP/1.1
Authorization: Bearer YOUR_AUTH_TOKEN

Response

{
    "id": "e3f246ed-7dce-4d22-9bc9-c50dc52d64e5",
    "name": "First Chat Thread",
    "created_at": "2024-02-21T09:49:57.185Z",
    "messages": [
        {
            "id": "77da83ae-8d33-4104-8521-11caee64cfd7",
            "content": "This is a message",
            "created_at": "2024-02-20T16:54:52.179Z",
            "response": {
                "id": "38a518fc-7e05-4fff-af4f-3aa63d2a03a2",
                "content": "This is an answer!",
                "state": "done",
                "created_at": "2024-02-20T16:54:52.192Z"
            }
        }
    ]
}

This endpoint retrieves a complete chat object, including all related messages and their responses, for a specific chat identified by its unique :id. It is designed to provide a comprehensive view of a conversation, making it easy to review the entire thread of communication within a particular topic.

Request Headers

Request Params

Response

Messages

The Messages endpoints within our API are a crucial component for facilitating communication with the agri1.ai system. These endpoints enable the creation of new messages in a chat and the retrieval of individual message objects. Leveraging these endpoints allows users to dynamically interact with chat threads, contributing to ongoing discussions or reviewing specific details of past communications.

Messages are always tied to a specific chat. A response to a message, commonly known as an answer, will be generated automatically by agri1.ai. The generation can take up to 30 seconds, depending on the complexity of your question. Therefore, it is necessary to monitor the processing state of the message object after its creation. Initially, the message will be in a pending state. Once the answer has been generated by agri1.ai, the state will change to done.

In most cases, the answer will be ready in less than a second.

POST /api/v1/chats/:id/messages

Example Request POST /api/v1/chats/:id/messages

curl -X POST 'https://api.agri1.ai/api/v1/chats/:id/messages' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
      "message": {
          "content": "This is my first question."
      }
}'

POST /api/v1/chats/:id/messages HTTP/1.1
Authorization: Bearer YOUR_AUTH_TOKEN
{
    "message": {
        "content": "First Chat Thread"
    }
}

Response

{
    "id": "708c3235-833f-4a35-b038-31778e10174b",
    "content": "This is my first question.",
    "created_at": "2024-02-26T15:51:20.491Z",
    "response": {
        "id": "72fecd2e-453e-4928-8e4f-134fd392cce3",
        "content": null,
        "state": "pending",
        "created_at": "2024-02-26T15:51:20.498Z"
    }
}

This endpoint allows users to send new messages to an existing chat, identified by its unique :id.

Request Headers

Request Params

Response

Errors

If you encounter errors, here are some common issues and their meanings:

GET /api/v1/messages/:id

Example Request GET /api/v1/messages/:id

curl -X GET 'https://api.agri1.ai/api/v1/messages/:id' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json'

POST /api/v1/messages/:id HTTP/1.1
Authorization: Bearer YOUR_AUTH_TOKEN

Response

{
    "id": "708c3235-833f-4a35-b038-31778e10174b",
    "content": "This is my first question.",
    "created_at": "2024-02-26T15:51:20.491Z",
    "response": {
        "id": "72fecd2e-453e-4928-8e4f-134fd392cce3",
        "content": "Hello! It seems like you might be getting started with our conversation. Is there anything specific you're interested in discussing related to agriculture, farming, or gardening? Feel free to share your thoughts or questions with me.",
        "state": "done",
        "created_at": "2024-02-26T15:51:20.498Z"
    }
}

This endpoint is designed to retrieve detailed information about a specific message within the agri1.ai system, identified by its unique :id. It enables users to access the content of individual messages, along with their status and any responses generated by agri1.ai, providing a comprehensive view of a message's contribution to a chat conversation.

Request Headers

Request Params

Response