Developer API

Build something great.

Developer API

Use Describe.ai's unique Developer API to build new experiences, apps and abilities for Deus.

01 Discover

Learn about our APIs and how to integrate them into your applications backend.

02 Build

Build the next generation of application experiences with minimal code.

03 Deploy

Deploy your application with one request or click with our fully managed infastructure.

new-clevr-logo (1).png

Developers

Introduction

About our API

At Describe.ai, our long-term vision is focused on building AI systems that can understand language at a human level. We believe that building strong systems that can explain concepts and ideas to users could fuel not only the next generation of transformative applications but the next generation of helpful AI for the world.  This is a big goal, but one we are determined to fulfill. While we aren't there yet,  today our engines can explain and understand computer code to significantly enhance software development.

Our debut system, Deus can explain code conversationally, generate documentation, answer questions (both in the context of your code and open domain) and fix buggy code. In the future, we plan to expand Deus's code capabilities further. If you have a use case, please reach out to us at sales@describe-ai.com.

Getting started

Let’s learn how to make your first request to the Developer API. Before you make a request, you need to have your API key.

To find your API key:

             1.       Login to the Dashboard for Describe.ai
             2.      At the top of the Dashboard, click  "Account"
             3.      Click "Developer API" and copy your API key

Please note, you must have an account to complete steps 1 to 3

Making your first API call to the Conversations API

Now that you have your API key, we can make a call to the Conversations API. This API allows you to have a natural conversation with Deus about your code. This same API is used in our no-code sandbox!

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import requests

import json

# Insert your API key in the authorization bearer 

auth_header = {"Authorization": "Bearer <YOUR API KEY>"}

# Start a session to use context when talking to Deus

sessionId = requests.post(

               "https://api.describe-ai.com/v1/sessions/create",

               headers=auth_header

            )

# Send a request to the Conversations API and get a response from Deus

conversation_response = requests.post(

                "https://api.describe-ai.com/v1/conversations/deus",

                headers=auth_header,

                json={

                        "sessionId": (json.loads(sessionId.text))["sessionId"]   # The ID of the session

                        "query": "How does this code work?",                # A query

                        "context": "print('hello world!')"                  # Your code

                     }

             )

 

print("Response from Deus Engine:", conversation_response['response']

Output

Response from Deus Engine: This code is greeting users with a simple hello world message.

After running the code snippet above, you should receive a similar output. There may be factors that cause this code not to work correctly that cause an error, such as:

-         Not having enough billable credits in your account
-         Invalid API keys
-         Invalid code file path

Documentation

Conversations API

Beta

The Conversations API is used to have a one-to-one conversation about code with Deus. This API is the same functionality that is used in our no-code sandbox's backend.

We recommend using this API if you are building a conversational interface.

Endpoint

Example

1
2
3
4
5
6
7
8
9
10
11
12
13

import requests

 

payload = {

            "context": "print('hello world!')",

            "sessionId": "1abc2-12z4..."

            "query": "Can you explain how this code works?"

          } 

conversation_response = requests.post(

                   "https://api.describe-ai.com/v1/conversations/deus",

                    headers={"Authorization": "Bearer <YOUR API KEY>"},

                    json=payload           

             )

Output

{

   "status": "success",

   "id": "conv-a1e3r-919cx-2bbn1",

   "response": "The print function is used to display information to the console.",

   "engine": "deus",

}

Arguments

query | string | Required

A question, reply or statement that will be used as input for Deus. To get the best results, it's recommended to use this parameter to only relate to coding questions or topics about your code; However, you can input anything into this parameter.

session | string | Required
This parameter allows our engines to remember your prior query, instead of treating it as an individual query. You must start a session by using the Sessions API and use the sessionId parameter for this argument. See the full example here

context | string | Optional, default: None

The code that you want to ask questions, be summarized etc. This parameter helps our engines provide more relevant responses to your queries. If this parameter is None, our engines will attempt to answer your query in an open-ended way using stored knowledge.

Sessions API

Beta

The Sessions API is used to start a contextual conversation with Deus.

Endpoint

Example

1
2
3
4
5
6
7
8
9

import requests

import json

 

response = requests.post("https://api.describe-ai.com/v1/sessions/create",

                         headers={"Authorization": "Bearer <YOUR API KEY>"

           )

 

print("Session ID:", (json.loads(response.text))["sessionId"])  

Output

{

   "status": "success",

   "id": "sessions-a1e3r-919cx-2bbn1",

   "sessionId": "a1db5-11opn-mi5y",

}

Arguments

For the Sessions API, you only need to provide your API key in the Authorization Header, no other arguments are needed.

Code Enhancement

Beta

The Code Enhancement API is used to allow Deus to automatically fix any bugs in your code. 

Endpoint

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import requests

 

payload = {

            "context": "print hello world",

            "iterations": 3

          } 

code_enhance = requests.post(

                   "https://api.describe-ai.com/v1/enhance/fix",

                    headers={"Authorization": "Bearer <YOUR API KEY>"},

                    json=payload           

             )

# Optional: Write the fixed code to a file

fixed_code = (json.loads(code_enhance))["code"]

with open("new_file.py", "w") as f:

     f.write(fixed_code)

Output

{

   "status": "success",

   "id": "enahnce-a1e3r-919cx-2bbn1",

   "code": "print('hello world!)'",

   "engine": "deus",

}

Arguments

code | string | Required

The buggy code represented as a string. We suggest using file I/O to read your code file's contents directly into the code parameter.

iteration | integer | Required

The number of cycles you allow Deus to improve your code. The more iterations you allow Deus, the higher the probability that Deus will identify and fix all bugs. 

NOTE: Be mindful when using this parameter, as one iteration counts as one billable unit. We recommend starting with 2 iterations and gradually increasing this value.

Documentation API

Beta

The Documentation API generates a detailed document about a provided code snippet that includes a summary, intended usage and recommended areas for testing.

Endpoint

Example

1
2
3
4
5
6
7
8
9
10
11

import requests

 

payload = {

            "context": "print hello world",

          } 

document = requests.post(

                   "https://api.describe-ai.com/v1/document/deus",

                    headers={"Authorization": "Bearer <YOUR API KEY>"},

                    json=payload           

             )

Output

{

   "status": "success",

   "id": "enahnce-a1e3r-919cx-2bbn1",

   "response": "Summary of code:\n The following code...",

   "engine": "deus",

}

Arguments

context | string | Required

The code that is being documented

iteration | integer | Required

The number of cycles you allow Deus to improve your code. The more iterations you allow Deus, the higher the probability that Deus will identify and fix all bugs. 

NOTE: Be mindful when using this parameter, as one iteration counts as one billable unit. We recommend starting with 2 iterations and gradually increasing this value.