NAV
BETA
shell http

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/v1/me' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN'
GET /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:

Header Value
Authorization Bearer YOUR_AUTH_TOKEN

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

HTTP Code Error Description
401 Unauthorized Indicates that either no auth-token was provided or the provided token is invalid or expired. Ensure you're correctly including the auth-token in the Authorization header.
403 Forbidden Suggests that the auth-token is valid, but it does not have the necessary permissions for the requested operation.

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 /v1/me

Example Request GET /v1/me

curl -X GET 'https://api.agri1.ai/v1/me' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN'
GET /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

Header Value
Authorization Bearer YOUR_AUTH_TOKEN

Request Params

None. This endpoint does not require any query parameters.

Response

Attribute Type Description
description string description of what the current token is used for
user object the user object
user.email string the email address associated with the requesting token

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 /v1/chats

Example Request POST /v1/chats

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

Header Value
Authorization Bearer YOUR_AUTH_TOKEN

Request Params

Attribute Type Required Description
chat object no the chat object
chat.name string no a short name or description of the chat

Response

Attribute Type Description
id string an unique uid of the chat
name string a short name or description of the chat
created_at string the creation date in UTC time in ISO 8601 format

Errors

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

HTTP Code Error Description
400 Bad Request The payload is malformed. Check the structure of your data you submitted to match the example payload.

GET /v1/chats/:id

Example Request GET /v1/chats

curl -X GET 'https://api.agri1.ai/v1/chats/:id' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN'
GET /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

Header Value
Authorization Bearer YOUR_AUTH_TOKEN

Request Params

Attribute Type Required Description
:id path parameter yes the chat_id of the corresponding chat you want to get

Response

Attribute Type Description
id string an unique uid of the chat
name string a short name or description of the chat
created_at string the creation date in UTC time in ISO 8601 format
messages array an array of all associated messages to the given chat.

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 /v1/chats/:id/messages

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

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

Header Value
Authorization Bearer YOUR_AUTH_TOKEN

Request Params

Attribute Type Required Description
message object no the message object
message.content string no the question you want to be answered

Response

Attribute Type Description
id string an unique uid of the chat
content string the question you asked
created_at string the creation date in UTC time in ISO 8601 format
response object the response object containing the answer to your question
response.id string a uniqe uid of the message
response.content string the answer generated by agri1.ai
response.state enum can be pending, processing, done or failed
response.created_at string the creation date in UTC time in ISO 8601 format

Errors

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

HTTP Code Error Description
400 Bad Request The payload is malformed. Check the structure of your data you submitted to match the example payload.

GET /v1/messages/:id

Example Request GET /v1/messages/:id

curl -X GET 'https://api.agri1.ai/v1/messages/:id' \
  --header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json'
POST /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

Header Value
Authorization Bearer YOUR_AUTH_TOKEN

Request Params

Attribute Type Required Description
:id path parameter yes the message_id of the message you want to get

Response

Attribute Type Description
id string an unique uid of the chat
content string the question you asked
created_at string the creation date in UTC time in ISO 8601 format
response object the response object containing the answer to your question
response.id string a uniqe uid of the message
response.content string the answer generated by agri1.ai
response.state enum can be pending, processing, done or failed
response.created_at string the creation date in UTC time in ISO 8601 format