Introduction

Welcome to the official beecrowd API!

By harnessing the power of our API, you can access information about our problems and build complementary tools to help the programming community.

Getting Started

To request access to the beecrowd API, you must send a message to our team containing the following information:

• Name of the application/website (so our users will recognize it);
• Name of the administrator or responsible for the application/website;
• Email of the administrator or responsible for the application/website (preferably in the company’s domain);
• Short description of the application/website;
• URL of the application/website;
• Hosts and/or IP address(es) of the server(s) that will issue the requests to our API;
• URL to which the beecrowd API will redirect the user after the authorization is successful.

To send your request, please follow the URL:
https://judge.beecrowd.com/en/contact

After submitting the request, the beecrowd team will contact you within at most three days.

General Considerations

• API endpoint:
  https://api.beecrowd.com.br

Requests

• By default, each application/website can issue 100 requests per hour to the API endpoint. This limit may be changed based on the application’s usage over time.

Authenticaion Token

• To issue requests to the API, you must have a TOKEN that is valid for one week. Once expired, you must get a new one with your account’s information.

• Generated Token Example:
  fyJ0eXPoOiLKO1QiLCJhbGciOiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBiyDVmXIy2pBvFkDEtBiPqVEC-U

Timestamp

• Timestamps are rendered in ISO-8601 format: 2012-02-24T19:42:12+00:00

Authentication

To generate the access token, use the code:

import json
import requests

url = 'https://api.beecrowd.com.br/applications/token'

data = {
  'email': '*********@api.beecrowd.com.br',
  'password': '*****'
}

headers = {
  'content-type': 'application/json',
  'accept': 'application/json'
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

Your authorization token should look like this:

{
  "token": "fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U"
}

• Generate Token:
  POST applications/token

Categories

To access the categories, use this code:

import requests

url = 'https://api.beecrowd.com.br/categories'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('GET', url, headers=headers)

print(response.text)

When you issue such request, the API will return a JSON similar to this one:

{
  "categories": [
    {
      "id": 1,
      "problems": 188,
      "en": {
        "name": "Beginner"
      },
      "es": {
        "name": "Principiante"
      },
      "pt": {
        "name": "Iniciante"
      }
    },
    {
      "id": 2,
      "problems": 526,
      "en": {
        "name": "Ad-Hoc"
      },
      "es": {
        "name": "Ad-Hoc"
      },
      "pt": {
        "name": "Ad-Hoc"
      }
    }
  ]
}

• List Categories:
  

GET: /categories

JSON Return

Parameter	Type	Description
id	integer	ID of the category
problems	integer	Number of problems in this category
en	object	An object with information in English
es	object	An object with information in Spanish
pt	object	An object with information in Portuguese

Internationalized Data

• The objects returned in the JSON that contains information in multiple languages will follow the format:

Parameter	Type	Description
name	string	The name of the category according to the language

Categories

ID	Category	Description
1	Beginner	Basic problems for anyone who has just started to program…
2	Ad-Hoc	Simulation Problems, Dates, Games and general Ad-Hoc…
3	String	Palindromes, Frequency, Ad-Hoc, LCS, String Manipulation…
4	Data Structures and Libraries	Queue, Stack, Sort, Map, Set…
5	Mathematics	Number Theory, Prime Numbers, Combinatorics, BigInteger…
6	Paradigms	Dynamic Programming, Binary Search, Greedy, Backtracking …
7	Graph	Flood Fill, MST, SSSP, DAG, Maximum Flow, Tree…
8	Computational Geometry	Points and Lines, Polygon…
9	SQL	Select, Insert, Update, Create

Problems

To obtain information about the problems, use this example:

import requests

url = 'https://api.beecrowd.com.br/problems/'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U'
}

response = requests.request('GET', url, headers=headers)

print(response.text)

The API will return a JSON with the available information for each problem:

{
  "problems": [
    {
      "id": 1001,
      "category": 1,
      "level": 1,
      "solved": 87353,
      "en": {
        "name": "Extremely Basic",
        "topics": "sequential"
      },
      "es": {
        "name": "Extremadamente Básico",
        "topics": "sequential"
      },
      "pt": {
        "name": "Extremamente Básico",
        "topics": "sequencial"
      }
    },
    {
      "id": 1002,
      "category": 1,
      "level": 1,
      "solved": 58115,
      "en": {
        "name": "Area of a Circle",
        "topics": "sequential"
      },
      "es": {
        "name": "Área del Círculo",
        "topics": "sequential"
      },
      "pt": {
        "name": "Área do Círculo",
        "topics": "sequencial"
      }
    },
  ]
}

• List Problems:
  GET /problems

JSON Return

Parameter	Type	Description
id	integer	ID of the problem
category	integer	ID of the category
level	integer	Level of the problem
solved	integer	Number of accepted solutions for the problem
en	object	An object with information in English
es	object	An object with information in Spanish
pt	object	An object with information in Portuguese

Internationalized Data

• The objects returned in the JSON that contains information in multiple languages will follow the format:

Parameter	Type	Description
name	string	The name of the category according to the language
topics	string	Represent the subject of the problem according to the language

Users

• It is also possible to obtain user profile information and a list of submissions. However, it is first necessary to get authorization from the user. You must redirect your user to:
  https://judge.beecrowd.com/authorizations/app/NAME

Redirect

• After the user authenticates at beecrowd (if it’s not already logged in) and gives permission, it will be redirected to the URL informed by you. You can pass the URL as a parameter:
  https://judge.beecrowd.com/en/authorizations/app/NAME?redirect=https://www.yourapplication.com/beecrowd/connect

• After the user authorized the application, beecrowd will redirect to (in this example):
  https://www.yourapplication.com/beecrowd/connect

beecrowd ID

• beecrowd will pass the user ID as an URL parameter upon redirection back to your system. Therefore, you will be able to correlate the beecrowd ID with the user information in your application/website. In this example that would be:
  https://www.yourapplication.com/beecrowd/connect?user=ID

With the user’s authorization, you will be able to access the profile and submissions.

Profile

To get the information of the user profile use this example:

import requests

url = 'https://api.beecrowd.com.br/users/profile/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('GET', url, headers=headers)

print(response.text)

This code, will return a JSON with the user’s data:

{
  "user": {
    "id": 1,
    "username": "The Guardian",
    "email": "[email protected]",
    "given_name": "Name",
    "family_name": "Family Name",
    "birthdate": "1986/11/19",
    "gender": 1,
    "country": 6,
    "city": "Example City",
    "state": "SP",
    "zone_info": 180,
    "language": "pt",
    "occupation": 1,
    "tracks": {
      3,
      4
    },
    "objectives": {
      1
    },
    "programming_language": 16,
    "statistics": {
      "rank": 12187,
      "solved": 56,
      "tried": 139,
      "submissions": 1336
    }
  }
}

• List user profile:
  GET /users/profile/ID

JSON Return

Parameter	Type	Description
user	object	An object representing the user
statistics	object	An object representing the user’s statistics
tracks	object	An object representing the user’s tracks
objectives	object	An object representing the user’s objectives

User Information

Parameter	Type	Description
id	integer	The identification code of the user
username	string	The registered username
email	string	The registered email
given_name	string	The registered given_name
family_name	string	The registered family_name
birthdate	string	The registered birthdate
gender	integer	The identification code of the user’s gender
country	string	The registered contry
city	string	The registered city
state	string	The registered state
zone_info	integer	The identification code of the user’s zone_info
language	string	The registered website language
programming_language	integer	The identification code of the user’s programming_language

Statistics Information

Parameter	Type	Description
rank	integer	The user’s place in the general rank
solved	integer	Number of problems solved by the user
tried	integer	Number of problems tried by the user
submissions	integer	Number of submissions sent by the user

Occupation

Value	Description
1	Student
2	Professional

Tracks

Value	Description
1	Development
2	QA / Testing
3	Data Science
4	Databases
5	Help Desk / Field Support
6	Design
7	Project Management

Objectives

Value	Description
1	Solve problems and Improve my programming skills
2	Prepare myself for technical interviews
3	Look for jobs and participate in contests/recruiting processes
4	Work as a freelancer and provide IT services to corporations
5	Participate in competitive programming contests/tournaments
6	Others

Register

To register a new user, use this example:

import requests

url = 'https://api.beecrowd.com.br/users/register'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

data = {
  'email': '[email protected]',
  'given_name': 'Name',
  'family_name': 'Family Name',
  'birthdate': '1983/07/21',
  'gender': 1,
  'country': 1,
  'city': 'Example City',
  'state': 'SP',
  'zone_info': 179,
  'language': 'pt',
  'occupation': 2,
  'tracks':[
    3,
    4
  ],
  'objectives':[
    1
  ]
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

This code, will return a JSON with the user’s identification code and a message:

{
  "message": "Registration completed.",
  "id": 341234
}

• Register new user:
  POST /users/register

User Information

Parameter	Type	Description	Mandatory	Default Value
email	string	The registered email	Yes	None
given_name	string	The registered given_name	Yes	None
family_name	string	The registered family_name	Yes	None
birthdate	string	The registered birthdate in the format yyyy/MM/dd	Yes	None
gender	integer	The identification code of the user’s gender	Yes	None
country	string	The registered contry	Yes	None
city	string	The registered city	Yes	None
state	string	The registered state	Yes	None
zone_info	integer	The identification code of the user’s zone_info	Yes	None
language	string	The registered website language	No	pt
programming_language	integer	The identification code of the user’s programming_language	No	7
tracks	object	The identification code of the user’s learning tracks	No	1
objectives	object	The identification code of the user’s objectives on the beecrowd plataform	No	1
occupation	integer	The user’s occupation	No	1

Programming Languages

• Each language and compiler has a unique identification code. The languages available for submission using the API are:

ID	Name	Compiler	Additional Time
5	Python 3	Python 3.4.3	+1s
6	Ruby	ruby 2.3.0	+5s
7	C#	mono 5.4.0	+2s
8	Scala	scalac 2.11.8	+2s
9	Lua	scalac lua 5.2.3	+1s
10	JavaScript	nodejs 8.4.0	+2s
14	C99	gcc 4.8.5, -std=c99 -O2 -lm	+0s
15	Kotlin	Kotlin 1.2.0	+2s
16	C++17	g++ 7.2.0, -std=c++17 -02 -lm	+0s
17	Haskell	ghc 7.6.3	+5s
18	Ocaml	ocamlc 4.01.0	+5s
19	Pascal	fpc 2.6.2	+0s
20	Python 3.8	Python 3.8.2	+1s
21	Java 14	OpenJDK 1.14.0	+2s
22	Dart	Dart 2.9	+2s
23	R	Dart Rscript 4.0.2	+2s
24	PHP	PHP 7.4.3	+2s
25	Swift	Swift 5.2.5	+2s
26	Clojure	Clojure 1.10	+5s
27	Ruby 2.7	Ruby 2.7.0	+5s
29	Lua 5.4	Lua 5.4.0	+1s
30	Javascript 12	Javascript 12.18	+2s
31	Rust	Rust 1.48	+0s
34	Elixir	Elixir 1.11.2	+2s
35	Python 3.9	Python 3.9.4	+1s
36	Python 3.9 AI	Python 3.9.4, V1.0	+1s

Occupations

Value	Description
1	Student
2	Professional

Tracks

Value	Description
1	Development
2	QA / Testing
3	Data Science
4	Databases
5	Help Desk / Field Support
6	Design
7	Project Management

Objectives

Value	Description
1	Solve problems and Improve my programming skills
2	Prepare myself for technical interviews
3	Look for jobs and participate in contests/recruiting processes
4	Work as a freelancer and provide IT services to corporations
5	Participate in competitive programming contests/tournaments
6	Others

Genders

Value	Description
1	Male
2	Female
48	Other
49	Prefer not to say

JSON Return

Parameter	Type	Description
id	integer	The identification code of the user
message	string	Return message

Edit

To edit a user, use this example:

import requests

url = 'https://api.beecrowd.com.br/users/edit/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

data = {
  'email': '[email protected]',
  'given_name': 'Name',
  'family_name': 'Family Name',
  'birthdate': '1983/07/21',
  'gender': 1,
  'country': 1,
  'city': 'Example City',
  'state': 'SP',
  'zone_info': 179,
  'language': 'pt',
  'occupation': 2,
  'tracks':[
    3,
    4
  ],
  'objectives':[
    1
  ]
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

This code, will return a JSON with the user’s identification code and a message:

{
  "message": "Edit completed.",
  "id": 341234
}

• Register new user:
  POST /users/edit/ID

User Information

Parameter	Type	Description	Mandatory
email	string	The registered email	No
given_name	string	The registered given_name	No
family_name	string	The registered family_name	No
birthdate	string	The registered birthdate in the format yyyy/MM/dd	No
gender	integer	The identification code of the user’s gender	No
country	string	The registered contry	No
city	string	The registered city	No
state	string	The registered state	No
zone_info	integer	The identification code of the user’s zone_info	No
language	string	The registered website language	Yes
programming_language	integer	The identification code of the user’s programming_language	Yes
tracks	object	The identification code of the user’s learning tracks	Yes
objectives	object	The identification code of the user’s objectives on the beecrowd plataform	Yes
occupation	integer	The user’s occupation	Yes

Programming Languages

• Each language and compiler has a unique identification code. The languages available for submission using the API are:

ID	Name	Compiler	Additional Time
5	Python 3	Python 3.4.3	+1s
6	Ruby	ruby 2.3.0	+5s
7	C#	mono 5.4.0	+2s
8	Scala	scalac 2.11.8	+2s
9	Lua	scalac lua 5.2.3	+1s
10	JavaScript	nodejs 8.4.0	+2s
14	C99	gcc 4.8.5, -std=c99 -O2 -lm	+0s
15	Kotlin	Kotlin 1.2.0	+2s
16	C++17	g++ 7.2.0, -std=c++17 -02 -lm	+0s
17	Haskell	ghc 7.6.3	+5s
18	Ocaml	ocamlc 4.01.0	+5s
19	Pascal	fpc 2.6.2	+0s
20	Python 3.8	Python 3.8.2	+1s
21	Java 14	OpenJDK 1.14.0	+2s
22	Dart	Dart 2.9	+2s
23	R	Dart Rscript 4.0.2	+2s
24	PHP	PHP 7.4.3	+2s
25	Swift	Swift 5.2.5	+2s
26	Clojure	Clojure 1.10	+5s
27	Ruby 2.7	Ruby 2.7.0	+5s
29	Lua 5.4	Lua 5.4.0	+1s
30	Javascript 12	Javascript 12.18	+2s
31	Rust	Rust 1.48	+0s
34	Elixir	Elixir 1.11.2	+2s
35	Python 3.9	Python 3.9.4	+1s
36	Python 3.9 AI	Python 3.9.4, V1.0	+1s

Occupations

Value	Description
1	Student
2	Professional

Tracks

Value	Description
1	Development
2	QA / Testing
3	Data Science
4	Databases
5	Help Desk / Field Support
6	Design
7	Project Management

Objectives

Value	Description
1	Solve problems and Improve my programming skills
2	Prepare myself for technical interviews
3	Look for jobs and participate in contests/recruiting processes
4	Work as a freelancer and provide IT services to corporations
5	Participate in competitive programming contests/tournaments
6	Others

Genders

Value	Description
1	Male
2	Female
48	Other
49	Prefer not to say

JSON Return

Parameter	Type	Description
id	integer	The identification code of the user
message	string	Return message

Submissions

To obtain the list of submissions sent by a given user, you can follow this example of request:

import requests

url = 'https://api.beecrowd.com.br/users/submissions/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('GET', url, headers=headers)

print(response.text)

This code, will return a JSON with the following data:

{
  "runs": [
    {
      "id": 3,
      "problem": 1001,
      "answer": 1,
      "time": 0,
      "created": "2012-02-24T19:42:12+00:00"
    },
    {
      "id": 4,
      "problem": 1002,
      "answer": 6,
      "time": 0,
      "created": "2012-02-24T19:42:34+00:00"
    },
    {
      "id": 6,
      "problem": 1003,
      "answer": 5,
      "time": 0,
      "created": "2012-02-24T19:42:44+00:00"
    },
  ]
}

• List submissions:
  GET: /users/submissions/ID

URL Parameters

Parameter	Values	Description
page	integer	Number of current page
sort	‘created’	Sort the submissions by received timestamp
direction	'asc’ OR 'desc’	Order the submissions by ascending or descending order

Pagination

• Notice that submissions are paginated. At the end of the returned JSON, additional pagination information will be returned, if there is a next page or previous page.

• To access other pages just use this example:
  GET: /users/submissions/ID?page=2

Sorting

• To sort the submissions by when they were received (created), you must use the sort key as an URL parameter.

• You can sort the result in ascending or descending order.

• To sort the submission just use this example:
  GET: /users/submissions/1?sort=created&direction=desc

JSON Return

Parameter	Type	Description
id	integer	Identification code for the submission
problem	integer	Identification code for the problem
answer	integer	Identification code for the answer
time	integer	Time took to run the solution
created	date	Date and time of when the submission was received

Answers

Id	Name
0	In Queue
1	Accept
2	Compilation Error
3	Runtime Error
4	Time Limit Exceeded
5	Presentation Error
6	Wrong Answer
9	Closed

• A short description of each one of the possible answers can be found at: answers

Submissions Challenge

To obtain the list of submissions sent by a given user, you can follow this example of request:

import requests

url = 'https://api.beecrowd.com.br/users/submissions-challenge/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('GET', url, headers=headers)

print(response.text)

This code, will return a JSON with the following data:

{
  "submissions": [
    {
      "id": 3,
      "challenge": 1001,
      "answer": 1,
      "time": 0,
      "created": "2012-02-24T19:42:12+00:00",
      "percentage": 100
    },
    {
      "id": 4,
      "challenge": 1002,
      "answer": 6,
      "time": 0,
      "created": "2012-02-24T19:42:34+00:00",
      "percentage": 95
    },
    {
      "id": 6,
      "challenge": 1003,
      "answer": 5,
      "language": 16,
      "time": 0,
      "created": "2012-02-24T19:42:44+00:00",
      "percentage": 10
    },
  ]
}

• List submissions:
  GET: /users/submissions-challenge/ID

URL Parameters

Parameter	Values	Description
page	integer	Number of current page
sort	'created’	Sort the submissions by received timestamp
direction	'asc’ OR 'desc’	Order the submissions by ascending or descending order

Pagination

• Notice that submissions are paginated. At the end of the returned JSON, additional pagination information will be returned, if there is a next page or previous page.

• To access other pages just use this example:
  GET: /users/submissions-challenge/ID?page=2

Sorting

• To sort the submissions by when they were received (created), you must use the sort key as an URL parameter.

• You can sort the result in ascending or descending order.

• To sort the submission just use this example:
  GET: /users/submissions-challenge/1?sort=created&direction=desc

JSON Return

Parameter	Type	Description
id	integer	Identification code for the submission
challenge	integer	Identification code for the challenge
answer	integer	Identification code for the answer
language	integer	Identification code for the programming language
time	integer	Time took to run the solution
created	date	Date and time of when the submission was received
percentage	integer	Percentage of answer

Answers

Id	Name
0	In Queue
1	Accept
2	Compilation Error
3	Runtime Error
4	Time Limit Exceeded
5	Presentation Error
6	Wrong Answer
9	Closed

• A short description of each one of the possible answers can be found at: answers

Activate

To activate an inactive user, use this example:

import requests

url = 'https://api.beecrowd.com.br/users/activate/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('POST', url, data=json.dumps(''), headers=headers)

print(response.text)

Once received by our system, the API will reply a JSON containing the identification code for this submission:

{
  "message": "User activated successfully.",
  "user_id": 1,
}

• Activate users:
  GET: /users/activate/ID

Deactivate

To deactivate an active user, use this example:

import requests

url = 'https://api.beecrowd.com.br/users/deactivate/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('POST', url, data=json.dumps(''), headers=headers)

print(response.text)

Once received by our system, the API will reply a JSON containing the identification code for this submission:

{
  "message": "User deactivated successfully.",
  "user_id": 1,
}

• Activate users:
  GET: /users/deactivate/ID

Runs

• Once your application was authorized by the beecrowd team to make submissions for problems, and you obtained the authorization of your end-user to submit solutions on behalf of that user, you can submit solutions to be evaluated by our judges and get submissions status.

Submit

To submit a source code, make a POST request, just as the example:

import json
import requests

url = 'https://api.beecrowd.com.br/runs/submit'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

source = """
#include <stdio.h>

int main() {
    int A, B, X;

    scanf("%d", &A);
    scanf("%d", &B);

    X=A+B;

    printf("X = %d\\n", X);

    return 0;
}
"""

data = {
    'user': ID,
    'problem': 1001,
    'language': 1,
    'source': source,
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

Once received by our system, the API will reply a JSON containing the identification code for this submission:

{
  "run":
    {
      "id":10382855,
      "user":119433,
      "problem":1001,
      "language":1,
      "created":"2018-05-15T14:03:41+00:00"
    }
}

• Submit solution for a problem:
  POST runs/submit

Languages

• Each language and compiler has a unique identification code. The languages available for submission using the API are:

ID	Name	Compiler	Additional Time
5	Python 3	Python 3.4.3	+1s
6	Ruby	ruby 2.3.0	+5s
7	C#	mono 5.4.0	+2s
8	Scala	scalac 2.11.8	+2s
9	Lua	scalac lua 5.2.3	+1s
10	JavaScript	nodejs 8.4.0	+2s
14	C99	gcc 4.8.5, -std=c99 -O2 -lm	+0s
15	Kotlin	Kotlin 1.2.0	+2s
16	C++17	g++ 7.2.0, -std=c++17 -02 -lm	+0s
17	Haskell	ghc 7.6.3	+5s
18	Ocaml	ocamlc 4.01.0	+5s
19	Pascal	fpc 2.6.2	+0s
20	Python 3.8	Python 3.8.2	+1s
21	Java 14	OpenJDK 1.14.0	+2s
22	Dart	Dart 2.9	+2s
23	R	Dart Rscript 4.0.2	+2s
24	PHP	PHP 7.4.3	+2s
25	Swift	Swift 5.2.5	+2s
26	Clojure	Clojure 1.10	+5s
27	Ruby 2.7	Ruby 2.7.0	+5s
29	Lua 5.4	Lua 5.4.0	+1s
30	Javascript 12	Javascript 12.18	+2s
31	Rust	Rust 1.48	+0s
34	Elixir	Elixir 1.11.2	+2s
35	Python 3.9	Python 3.9.4	+1s
36	Python 3.9 AI	Python 3.9.4, V1.0	+1s

Problems

Source Code

• You should submit the source code directly in the body of the request. Notice that you should escape special characters in Python.
  For further references, please check the Python documentation: https://docs.python.org/2.0/ref/strings.html

• You can also read the source code from an external file and then submit the request.

Example of how to submit a source code from a file:

import json
import requests

url = 'https://api.beecrowd.com.br/runs/submit'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer '' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

PATH_TO_FILE = '/home/user/1001.c'

solution = open(PATH_TO_FILE, 'r')

source = solution.read()

data = {
  'user': 119433,
  'problem': 1001,
  'language': 1,
  'source': source,
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

Status

To obtain the information of a submission sent by a given user and run, you can follow this example of request:

import requests

url = 'https://api.beecrowd.com.br/runs/status/ID?run=RUN_ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('GET', url, headers=headers)

print(response.text)

This code, will return a JSON with the following data:

{
  "run": [
    {
      "id": 3,
      "user": 1,
      "problem": 1001,
      "answer": 1,
      "time": 0,
      "created": "2012-02-24T19:42:12+00:00",
      "percentage": 100
    },
  ]
}

• Run Status:
  GET: /runs/status/ID?run=RUN_ID

URL Parameters

Parameter	Values	Description
run	integer	Identification code for the submission

Submissions

• Once your application was authorized by the beecrowd team to make submissions for challenges, and you obtained the authorization of your end-user to submit solutions on behalf of that user, you can submit solutions to be evaluated by our judges and get submissions status.

Submit

To submit a source code, make a POST request, just as the example:

import json
import requests

url = 'https://api.beecrowd.com.br/submissions/submit'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

source = """
#include <stdio.h>

int main() {
    int A, B, X;

    scanf("%d", &A);
    scanf("%d", &B);

    X=A+B;

    printf("X = %d\\n", X);

    return 0;
}
"""

data = {
    'user': ID,
    'challenge': 1131,
    'language': 1,
    'source': source,
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

Once received by our system, the API will reply a JSON containing the identification code for this submission:

{
  "submission":
    {
      "id":10382855,
      "user":119433,
      "challenge":1044,
      "language":1,
      "created":"2018-05-15T14:03:41+00:00"
    }
}

• Submit solution for a problem:
  POST submissions/submit

Languages

• Each language and compiler has a unique identification code. The languages available for submission using the API are:

ID	Name	Compiler	Additional Time
5	Python 3	Python 3.4.3	+1s
6	Ruby	ruby 2.3.0	+5s
7	C#	mono 5.4.0	+2s
8	Scala	scalac 2.11.8	+2s
9	Lua	scalac lua 5.2.3	+1s
10	JavaScript	nodejs 8.4.0	+2s
14	C99	gcc 4.8.5, -std=c99 -O2 -lm	+0s
15	Kotlin	Kotlin 1.2.0	+2s
16	C++17	g++ 7.2.0, -std=c++17 -02 -lm	+0s
17	Haskell	ghc 7.6.3	+5s
18	Ocaml	ocamlc 4.01.0	+5s
19	Pascal	fpc 2.6.2	+0s
20	Python 3.8	Python 3.8.2	+1s
21	Java 14	OpenJDK 1.14.0	+2s
22	Dart	Dart 2.9	+2s
23	R	Dart Rscript 4.0.2	+2s
24	PHP	PHP 7.4.3	+2s
25	Swift	Swift 5.2.5	+2s
26	Clojure	Clojure 1.10	+5s
27	Ruby 2.7	Ruby 2.7.0	+5s
29	Lua 5.4	Lua 5.4.0	+1s
30	Javascript 12	Javascript 12.18	+2s
31	Rust	Rust 1.48	+0s
34	Elixir	Elixir 1.11.2	+2s
35	Python 3.9	Python 3.9.4	+1s
36	Python 3.9 AI	Python 3.9.4, V1.0	+1s

Challenges

Source Code

• You should submit the source code directly in the body of the request. Notice that you should escape special characters in Python.
  For further references, please check the Python documentation: https://docs.python.org/2.0/ref/strings.html

• You can also read the source code from an external file and then submit the request.

Example of how to submit a source code from a file:

import json
import requests

url = 'https://api.beecrowd.com.br/submissions/submit'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer '' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

PATH_TO_FILE = '/home/user/1001.c'

solution = open(PATH_TO_FILE, 'r')

source = solution.read()

data = {
  'user': 119433,
  'challenge': 1001,
  'language': 1,
  'source': source,
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

Status

To obtain the information of a submission sent by a given user and run, you can follow this example of request:

import requests

url = 'https://api.beecrowd.com.br/submissions/status/ID?run=RUN_ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('GET', url, headers=headers)

print(response.text)

This code, will return a JSON with the following data:

{
  "submission": [
    {
      "id": 3,
      "user": 1,
      "challenge": 1089,
      "answer": 1,
      "time": 0,
      "created": "2012-02-24T19:42:12+00:00",
      "percentage": 100
    },
  ]
}

• Submission Status:
  GET: /submissions/status/ID?run=RUN_ID

URL Parameters

Parameter	Values	Description
run	integer	Identification code for the submission

Professors

• It is also possible to obtain professor profile information, register new professors, edit, activate and deactivate professors. However, it is first necessary to get authorization from a professor that has an account not created by the api. You must redirect your request to:
  https://academic.beecrowd.com/professors/app/NAME

Profile

To get the information of the professor profile use this example:

import requests

url = 'https://api.beecrowd.com.br/professors/profile/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('GET', url, headers=headers)

print(response.text)

This code, will return a JSON with the professor’s data:

{
  "professor": {
    "id": 1,
    "username": "The Guardian",
    "email": "[email protected]",
    "given_name": "Name",
    "family_name": "Family Name",
    "gender": 1,
    "country": 7,
    "city": "Example City",
    "state": "SP",
    "zone_info": 179,
    "type": "professor",
    "language": "en",
  }
}

• List professor profile:
  GET /professors/profile/ID

JSON Return

Parameter	Type	Description
professor	object	An object representing the professor

Professor Information

Parameter	Type	Description
id	integer	The identification code of the professor
username	string	The registered username
email	string	The registered email
given_name	string	The registered given_name
family_name	string	The registered family_name
gender	integer	The identification code of the professor’s gender
country	integer	The identification code of the contry
city	string	The registered city
state	string	The registered state
zone_info	integer	The identification code of the professor’s zone_info
language	string	The registered website language
type	string	The professor account type

Type

Value	Description
professor	Can create, edit and view disciplines, invite students, show key, export students, view and export progress,
monitor	Cannot create and edit disciplines, invite students, export progress

Genders

Value	Description
1	Male
2	Female

Register

To register a new professor, use this example:

import requests

url = 'https://api.beecrowd.com.br/professors/register'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

data = {
  'email': '[email protected]',
  'given_name': 'Name',
  'family_name': 'Family Name',
  'gender': 1,
  'country': 1,
  'city': 'Example City',
  'state': 'SP',
  'zone_info': 179,
  'language': 'pt',
  'type': "coach",
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

This code, will return a JSON with the professor’s identification code and a message:

{
  "message": "Registration completed.",
  "professor_id": 341234
}

• Register new professor:
  POST /professors/register

Professor Information

Parameter	Type	Description	Optional	Default Value
email	string	The registered email	No	None
given_name	string	The registered given_name	No	None
family_name	string	The registered family_name	No	None
gender	integer	The identification code of the professor’s gender	No	None
country	integer	The identification code of the contry	No	None
city	string	The registered city	No	None
state	string	The registered state	No	None
zone_info	integer	The identification code of the professor’s zone_info	No	None
language	string	The registered website language	Yes	pt
type	string	The professor account type	Yes	professor

Type

Value	Description
professor	Can create, edit and view disciplines, invite students, show key, export students, view and export progress,
monitor	Cannot create and edit disciplines, invite students, export progress

Language

Value	Description
pt	Portuguese
en	English
es	Spanish

Genders

Value	Description
1	Male
2	Female

JSON Return

Parameter	Type	Description
id	integer	The identification code of the professor
message	string	Return message

Edit

To edit a professor, use this example:

import requests

url = 'https://api.beecrowd.com.br/professors/edit/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

data = {
  'email': '[email protected]',
  'given_name': 'Name',
  'family_name': 'Family Name',
  'gender': 1,
  'country': 1,
  'city': 'Example City',
  'state': 'SP',
  'zone_info': 179,
  'language': 'pt',
  'type': "coach",
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

This code, will return a JSON with the professor’s identification code and a message:

{
  "message": "Edit completed.",
  "professor_id": 341234
}

• Register new professor:
  POST /professors/edit/ID

Professor Information

Parameter	Type	Description	Optional	Default Value
email	string	The registered email	No	None
given_name	string	The registered given_name	No	None
family_name	string	The registered family_name	No	None
gender	integer	The identification code of the professor’s gender	No	None
country	integer	The identification code of the contry	No	None
city	string	The registered city	No	None
state	string	The registered state	No	None
zone_info	integer	The identification code of the professor’s zone_info	No	None
language	string	The registered website language	Yes	pt
type	string	The professor account type	Yes	professor

Type

Value	Description
professor	Can create, edit and view disciplines, invite students, show key, export students, view and export progress,
monitor	Cannot create and edit disciplines, invite students, export progress

Language

Value	Description
pt	Portuguese
en	English
es	Spanish

Genders

Value	Description
1	Male
2	Female

JSON Return

Parameter	Type	Description
id	integer	The identification code of the professor
message	string	Return message

Activate

To activate an inactive professor, use this example:

import requests

url = 'https://api.beecrowd.com.br/professors/activate/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('POST', url, data=json.dumps(''), headers=headers)

print(response.text)

Once received by our system, the API will reply a JSON containing the identification code for this submission:

{
  "message": "Professors activated successfully.",
  "professor_id": 1,
}

• Activate professors:
  GET: /professors/activate/ID

Deactivate

To deactivate an active professor, use this example:

import requests

url = 'https://api.beecrowd.com.br/professors/deactivate/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('POST', url, data=json.dumps(''), headers=headers)

print(response.text)

Once received by our system, the API will reply a JSON containing the identification code for this submission:

{
  "message": "Professor deactivated successfully.",
  "professor_id": 1,
}

• Activate professors:
  GET: /professors/deactivate/ID

Disciplines

• Once your application was authorized by the beecrowd team to create disciplines, and you obtained the authorization of your professor, you can create, edit, visualize disciplines and allow other professors to access other disciplines.

Create

To create a new discipline for your professors, use this example:

import json
import requests

url = 'https://api.beecrowd.com.br/disciplines/create'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

data = {
    'name': 'My New Discipline',
    'professor': 1131,
    'mode': 2,
    'description': 'My new discipline description',
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

Once received by our system, the API will reply a JSON containing the identification code for this discipline:

{
  "message": "Discipline created successfully.",
  "discipline_id": 1044
}

• Create a discipline for a professor:
  POST disciplines/create

Modes

• The disciplines mode available for the disciplines using the API are:

ID	Mode
1	Programming
2	SQL

JSON Return

Parameter	Type	Description
discipline_id	integer	The identification code of the discipline
message	string	Return message

Edit

To edit the information of a disicipline, you can follow this example of request:

import requests

url = 'https://api.beecrowd.com.br/disciplines/edit/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

data = {
    'name': 'My New Discipline',
    'mode': 2,
    'description': 'My new discipline description',
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

This code, will return a JSON with the following data:

{
  "message": "Edit completed.",
  "discipline_id": 1044
}

• Submission Status:
  POST: /disciplines/edit/ID

JSON Return

Parameter	Type	Description
discipline_id	integer	The identification code of the discipline
message	string	Return message

View

To obtain the information of a discipline, you can follow this example of request:

import requests

url = 'https://api.beecrowd.com.br/disciplines/view/ID'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

response = requests.request('GET', url, headers=headers)

print(response.text)

This code, will return a JSON with the following data:

{
  "name": "My New Discipline",
  "description": "My new discipline description",
  "professor": 1131,
  "mode": 2,
  "auxiliaries": {
    1131,
    1232
  },
}

• Submission Status:
  GET: /disciplines/view/ID

Allow

To add an auxiliar professor to a discipline, you can follow this example of request:

import requests

url = 'https://api.beecrowd.com.br/disciplines/allow'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U',
}

data = {
    'professor': 1131,
    'discipline': 1044,
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

This code, will return a JSON with the following data:

{
  "message" => "Edit completed.",
  "discipline_id": 1044
}

• Submission Status:
  POST: /disciplines/allow

JSON Return

Parameter	Type	Description
discipline_id	integer	The identification code of the discipline
message	string	Return message

Students

To add a student to one of your teacher’s disciplines, use this example:

import requests

url = 'https://api.beecrowd.com.br/students/add'

headers = {
  'content-type': 'application/json',
  'accept': 'application/json',
  'authorization': 'Bearer ' + 'fyJ0eXPoOiLKO1QiiJIUzO1NiJ9.eyJzdWIiOjF9.5_KOZGatI2yINbYIBipBvFkDEtBiPqVEC-U'
}

data = {
  'user': 3134,
  'discipline': 8137
}

response = requests.request('POST', url, data=json.dumps(data), headers=headers)

print(response.text)

The API will return a JSON with the available information for each problem:

{
  "message": "Student added to the discipline."
}

• Add Student:
  POST /students/add

JSON Return

Parameter	Type	Description
message	string	ID of the problem

Errors

The URI Online Judge API uses the following error codes:

Error Code	Meaning
401	Missing authorization – Your don’t have authorization
404	Not Found – The specified URL could not be found