AriGPT API Documentation

You can make AriGPT requests using the official AriGPT API. By using this API you agree to the Privacy Policy and the Terms of Service.

At any point AriGPT API may return a rate limiting response with HTTP code 429 and JSON:

{
    "error": "You are being rate limited, please try again later"
}

For sample API usage see gptapi.py.

For Bots

If you're planning on making a bot, an AriGPT client, or anything using the AriGPT API in any way repetitively, I recommend the following topology:

user prompt
    -> prompt queue
prompt worker
    -> sleep 1.1 min
       or sleep 1.1 hour
       or sleep 1.1 day
    -> /gpt/api/config
    -> /gpt/api/query
    -> ID to answer queue
answer worker
    -> sleep 1.1 min
       or sleep 1.1 hour
    -> /gpt/api/answers
    -> process
when call to /gpt/answer/<id>/file/<filename>
    -> cache in FS
    -> retrieve

Don't forget to handle errors and retry after some time and drop from queue if it keeps erroring.

This topology ensures that your app never hangs and strictly follows rate limits (sleeping for just a little longer than the rate limit) so you don't get your IP address banned temporarily (usually 40-60 minutes)

For rate limit delegation, contact me.

API Routes

If possible, follow API cache headers.

API routes, descriptions, documentation, and rate limits:

GET /gpt/api/config -- Request configuration (1/min) -- IMPORTANT ENDPOINT

You must call to this API every time you make a POST request. This request will return JSON:
```
{
    "nonce": "string",
    "difficulty": N,
}
```
And this route will return a __Host-session cookie which you must include with every API call.

With this JSON data, you must solve a Proof-of-Work challenge: find such ASCII string S with all digits (0-9) that is less or equal to 32 bytes but not empty, such that SHA256(nonce + S).hex() starts with at least difficulty zero (0) characters.

e.g.,
```
state:

    nonce = "9c2e"
    difficulty = 5

hence one possible solution,

    solution = "30078260"

because,

    SHA256("9c2e" + "30078260") = SHA256("9c2e30078260") = "00000627dded0e0b3632ef7d0496e40ac34ac80dd42afa628eecd5b7414dee64"
```
Proof-of-Work tokens expire after 16 minutes and cannot be re-used after one request. You must use a new token.
POST /gpt/api/query -- Post a new AriGPT query (1/min, 8/hour, 16/day)

You must POST JSON data such that it has the following scheme:
```
{
    "solution": "... your proof of work solution",
    "prompt": "... your AriGPT prompt",
}
```
If you omit one or both of the keys, or omit the __Host-session cookie, you will receive an error response with HTTP code 400 and a JSON body including a human readable error in the "error" key. On invalid Proof-of-Work solution, you will also receive an error JSON response with HTTP code 401.

On success, you will receive a JSON response in the following scheme:
```
{
    "id": "... uuid"
}
```
e.g.,
```
{
    "id": "27b9ab92-db72-4eb3-a8f7-4d4f70297a10"
}
```
This is the question ID.
GET /gpt/api/answer/<id> -- Get AriGPT thread (1/min)

To get an AriGPT question thread in JSON, make a request to this API. Upon request you will receive one of two responses:
1. An error response (404): Returns a human readable error in the "error" key with HTTP code 404. Indicates that the question has not been answered or does not exist yet.
2. A success response in the scheme:
```
{
    "question": "... question",
    "answer": "... answer (markdown)",
    "answeree": "... Ari ID (e.g., af546cbf796eebbf3c03)",
    "time": ... timestamp,
    (optional) "files": [
        {
            "filename": "filename",
            "mimetype": "some/mimetype",
            "size": ... file size in bytes
        },
        {
            "filename": "filename1",
            "mimetype": "some/mimetype",
            "size": ... file size in bytes
        }
    ]
}
```
The question is the original question. The answer is the markdown answer by the answeree (an Ari). The timestamp is a UNIX timestamp indicating when the question was created. The optionally present files array includes an array of filenames related to this question.
GET /gpt/answer/<id>/file/<filename> -- Get file content (lenient)

Upon request, this will return the file content of a requested file related to the question.

Please cache the file content for up to 30 days to save bandwidth :) This is optional, but not only will it save you from redownloading content, it will also improve the usability of AriGPT for everyone else. This is pretty much the only route where caching matters, but other routes do have Cache-Control and Expires headers set as a suggestion.
GET /gpt/api/stats -- Get statistics of AriGPT (1/min)

Upon request, this route will return JSON indicating AriGPT statistics useful for API usage:
```
{
    "count": ... question count,
    "files": ... files count,
    "pages": ... pages count
}
```

GET /gpt/api/files - Get all files hosted on AriGPT (1/min)

Upon request this will return a JSON array of objects describing files and their relation to questions:

[
    {
        "filename": "filename",
        "mimetype": "some/mimetype",
        "size": ... file size in bytes,
        "question": "question ID (e.g., 27b9ab92-db72-4eb3-a8f7-4d4f70297a10)",
    },
    {
        "filename": "filename1",
        "mimetype": "some/mimetype",
        "size": ... file size in bytes,
        "question": "question ID (e.g., 27b9ab92-db72-4eb3-a8f7-5d4f70297a13)",
    },
    ...
]

GET /gpt/api/page/<n> -- Get a list of questions on a specific page (1/min, 8/hour)

Upon request this route will return an array of JSON objects similar to the /gpt/api/answer/<id> route, except multiple in one list:

[
    {
        "id": "... question ID",
        "question": "... question",
        "answer": "... answer (markdown)",
        "answeree": "... Ari ID (e.g., af546cbf796eebbf3c03)",
        "time": ... timestamp,
        (optional) "files": [
            {
                "filename": "filename",
                "mimetype": "some/mimetype",
                "size": ... file size in bytes
            },
            {
                "filename": "filename1",
                "mimetype": "some/mimetype",
                "size": ... file size in bytes
            }
        ]
    },
    {
        "id": "... question ID",
        "question": "... question",
        "answer": "... answer (markdown)",
        "answeree": "... Ari ID (e.g., af546cbf796eebbf3c03)",
        "time": ... timestamp,
        (optional) "files": [
            {
                "filename": "filename",
                "mimetype": "some/mimetype",
                "size": ... file size in bytes
            },
            {
                "filename": "filename1",
                "mimetype": "some/mimetype",
                "size": ... file size in bytes
            }
        ]
    },
    ...
]

You may also optionally supply {"per_page": N} in request body where abs(N) is between 1 and 128 to get a paginate amount of items.

The route may return {"error": ...} in the results.

GET /gpt/api/answers -- Get specific answers (1/min, 8/hour)

Upon request with body of a JSON array of question IDs (["...", "...", ...]) this route will return an array of JSON objects similar to the /gpt/api/answer/<id> route, except multiple in one list:

[
    {
        "id": "... question ID",
        "question": "... question",
        "answer": "... answer (markdown)",
        "answeree": "... Ari ID (e.g., af546cbf796eebbf3c03)",
        "time": ... timestamp,
        (optional) "files": [
            {
                "filename": "filename",
                "mimetype": "some/mimetype",
                "size": ... file size in bytes
            },
            {
                "filename": "filename1",
                "mimetype": "some/mimetype",
                "size": ... file size in bytes
            }
        ]
    },
    {
        "id": "... question ID",
        "question": "... question",
        "answer": "... answer (markdown)",
        "answeree": "... Ari ID (e.g., af546cbf796eebbf3c03)",
        "time": ... timestamp,
        (optional) "files": [
            {
                "filename": "filename",
                "mimetype": "some/mimetype",
                "size": ... file size in bytes
            },
            {
                "filename": "filename1",
                "mimetype": "some/mimetype",
                "size": ... file size in bytes
            }
        ]
    },
    ...
]

The route may return {"error": ...} and {"error": ..., "id": ...} (error related to question ID) in the results. No more than 128 IDs per request.