preloader

REST API v1 Reference

This is the MyReport API 1st version reference documentation.

Introduction

The MyReport API is organized around REST.

Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The MyReport API doesn’t support bulk updates.

You can work on only one object per request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authentication

The MyReport API can be accessed with API keys to authenticate requests. You can view and manage your API keys in the MyReport Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Use your API key in the X-api-key header.

curl https://myreportgw.alaba.ai/v1/api_credit -H "X-api-key: API_KEY"
# replace API_KEY with yours

Errors

MyReport uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.) or a temporary error from another platform that we do not control.

Codes in the 5xx range indicate an error with MyReport’s servers (these are rare).

For 4xx errors that could be handled programmatically (e.g., a report identifier is not found) we include an internal result that briefly explains the error reported.

code

Integer. HTTP response code.

result

String. For some errors that could be handled programmatically, a short string indicating the error code reported.

message

String. A human-readable message providing more details about the error.

Codes summary table
Code Result Description
200 ok Everything worked as expected.
400 invalid-argument The request was unacceptable, often due to missing a required parameter.
401 unauthorized No valid API key provided.
 403 permission-denied The API key doesn’t have permissions to perform the request.
404 no-found The requested resource doesn’t exist.
409 already-exists The request conflicts with another request (perhaps due to using the same idempotent key).
412 precondition-failed The request conflicts with another request (perhaps due to using the same idempotent key).
 419 aborted Temporary failure lead to abort because some unavailable resource. Can be retried.
 420 unknown Temporary unknown failure. Can be retried.
 429 resource-exahusted Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 internal Something went wrong on MyReport’s end. (These are rare.)

Operations

These are the operations supported by the REST API.

Detect and launch reports

POST /detect_and_launch

Detects if the input text contains requests for one or more reports. If such requests are found, it initiates the report generation process for each. Reports that cannot be launched due to credit or quota limitations will be disregarded.

Parameters
Name Type Default value Description
description string minLength=60 maxLength=100000 None Text including potential requests or instructions to generate one or many reports.
Responses
Code Content-Type Description Example
200 application/json Successfully launched report(s) {'code': 200, 'result': 'ok', 'message': '✅ Successfully launched 1 report(s)', 'reports': [{'id': 'dXjccHVY6JfAvXhzjaaI', 'message': '✅ Successfully launched report dXjccHVY6JfAvXhzjaaI'}]}
210 application/json No report requests detected in the input text {'code': 210, 'result': 'accepted', 'message': '⚠️ No valid report request(s) detected in the input data, nothing will be launched'}
419 application/json Report created as a draft in the database but not launched due to some error, if you receive an ‘id’ (meaning that the rollback failed) you can retry the operation with relaunch using that id code {'code': 419, 'result': 'aborted', 'message': '⚠️ Report inserted but NOT launched'}
400 application/json Bad request due to invalid input {'code': 400, 'result': 'invalid-argument', 'message': "❗ Invalid field value 'XXX' for [citations_format], it should be one of : 'IEEE', 'APA', 'MLA'"}
401 application/json Unauthorized request {'code': 401, 'result': 'unauthorized', 'message': '❗ Unauthorized'}
402 application/json No available plan {'code': 403, 'result': 'permission-denied', 'message': '❗ No available subscribed plan with remaining credit to execute this report'}
412 application/json Precondition failed {'code': 412, 'result': 'precondition-failed', 'message': '❗ No access to shared drive link, please grant view permissions to googledrive@myreport-2022.iam.gserviceaccount.com'}
409 application/json Free queue is full (when using a free plan), please retry later {'code': 429, 'result': 'resource-exhausted', 'message': '⚠️ Overload for free queue'}
429 application/json Too many reports in execution {'code': 409, 'result': 'already-exists', 'message': '⚠️ Too many concurrent reports (max=1)'}
420 application/json Temporary failure {'code': 420, 'result': 'unknown', 'message': '❗ Unknown failure'}
500 application/json Internal server error {'code': 500, 'result': 'internal', 'message': 'Server unavailable'}
Successful response output object
Name Type Description Example
code integer HTTP response code 200
result string Internal response ok
message string Human readable message explaining the response ✅ Successfully launched 1 report(s)
reports array
reports.id string Unique identifier for the report dXjccHVY6JfAvXhzjaaI
reports.message string Individual launch response message and warnings for a specific report ✅ Successfully launched report dXjccHVY6JfAvXhzjaaI
Successful response output object
Name Type Description Example
code integer HTTP response code 210
result string Internal response accepted
message string Human readable message explaining the response ⚠️ No valid report request(s) detected in the input data, nothing will be launched
Example cURL
DATA='
{
    "description": "Hi John,\nPlease I need you to create a document with the last marketing results of our CocinatorPlus product, with 3 or more pages, and use our product page (https://www.cocinator.com/basic/index.html) for the introduction.\nThanks,\nMary"
}
'
curl -X POST -H "X-api-key: API_KEY" -H "Content-Type: application/json" \
-d "$DATA" https://myreportgw.alaba.ai/v1/detect_and_launch 
# replace API_KEY with yours
Example response
{
    "code": 200,
    "result": "ok",
    "message": "Successfully launched 1 report(s)",
    "reports": [
        {
            "id": "dXjccHVY6JfAvXhzjaaI",
            "message": "\u2705 Successfully launched report dXjccHVY6JfAvXhzjaaI"
        }
    ]
}
Example response
{
    "code": 210,
    "result": "accepted",
    "message": "No valid report request(s) detected in the input data, nothing will be launched"
}

Create and launch a new report

POST /create_and_launch

Generates a report based on input criteria and launches the report generation process.

Parameters
Name Type Default value Description
title string minLength=1 maxLength=200 None Title of the report.
description string minLength=60 maxLength=800 None Detailed description of the report.
additional_indications string maxLength=10000 Optional. Additional instructions.
size string ['brief', 'short', 'regular', 'long', 'xlong'] regular Optional. Approximate report size, the accepted values are: “brief” (about 1000 words), “short” (about 2000 words), “regular” (about 3500 words), “long” (about 5000 words), “xlong” (about 8000 words).
output_language string ['en', 'es', 'fr', 'pt'] en Optional. Language of the final document, ISO-639-1 alpha-2 code, accepted values are: “en” (English), “es” (Spanish), “fr” (French), “pt” (Portuguese).
citations_format string ['IEEE', 'APA', 'MLA'] IEEE Optional. Citation style.
inlined_citations boolean False Optional. Whether citations should be inline.
creative_analysis boolean False Optional. Enable creative analysis to allow the AI to generate content with its own insights and opinions (clearly marked as such). Additionally, it enables the creation of supporting elements like images, tables, and charts, which will also be explicitly labeled. Please note that these AI-generated materials may not always be based on verified information. Use them at your own discretion and risk.
www_search boolean True Optional. Enable web search (dismissed if custom documents are provided or constricted to specific sites to search).
sites_to_search array [] Optional. List of specific domains to use in the search instead of the whole WWW (up to 5 sites).
sites_to_avoid array [] Optional. List of domains to avoid in search.
links_to_collect array [] Optional. Specific URLs to collect information from. Only the first page or document is read, not following sub-links and not searching inside the website. Use publicly accessible links. Avoid sites that require a user login to work with. You can include up to 20 links. Web pages (html), documents (pdf, docx, rtf, txt, odt, epub), spreadsheets (xlsx, ods, csv) presentations (pptx, odp) and images (jpeg, png, svg, tiff) are accepted (by now). The page content should be in the supported languages. WARNING: some anti-bot mechanisms can block the information retrieval.
shared_drive_link string Optional. Google Drive folder or file link for private document sources. The system will use all the files found in folder and sub-folders. You can include up to 100 files with max 100 Mb size each. Google files (gdoc, gsheet, gslides) with less than 10 Mb size each, web pages (html), documents (pdf, docx, rtf, txt, epub, gdoc), spreadsheets (xlsx, ods, csv, gsheet), presentations (pptx, odp, gslides) and images (jpeg, png, svg, tiff) are accepted (by now). The information should be in the supported output languages. The files will be read ONLY during the report generation, and will NOT be used to train any AI. WARNING: you need to grant viewer permissions to us (check our web FAQ) and please remove the permissions when the report is ready.
Responses
Code Content-Type Description Example
200 application/json Successfully launched report {'code': 200, 'result': 'ok', 'message': '✅ Successfully launched report', 'id': 'zeoNSzmtEBxJSofisYWt'}
419 application/json Report created as a draft in the database but not launched due to some error, if you receive an ‘id’ (meaning that the rollback failed) you can retry the operation with relaunch using that id code {'code': 419, 'result': 'aborted', 'message': '⚠️ Report inserted but NOT launched'}
400 application/json Bad request due to invalid input {'code': 400, 'result': 'invalid-argument', 'message': "❗ Invalid field value 'XXX' for [citations_format], it should be one of : 'IEEE', 'APA', 'MLA'"}
401 application/json Unauthorized request {'code': 401, 'result': 'unauthorized', 'message': '❗ Unauthorized'}
402 application/json No available plan {'code': 403, 'result': 'permission-denied', 'message': '❗ No available subscribed plan with remaining credit to execute this report'}
412 application/json Precondition failed {'code': 412, 'result': 'precondition-failed', 'message': '❗ No access to shared drive link, please grant view permissions to googledrive@myreport-2022.iam.gserviceaccount.com'}
409 application/json Free queue is full (when using a free plan), please retry later {'code': 429, 'result': 'resource-exhausted', 'message': '⚠️ Overload for free queue'}
429 application/json Too many reports in execution {'code': 409, 'result': 'already-exists', 'message': '⚠️ Too many concurrent reports (max=1)'}
420 application/json Temporary failure {'code': 420, 'result': 'unknown', 'message': '❗ Unknown failure'}
500 application/json Internal server error {'code': 500, 'result': 'internal', 'message': 'Server unavailable'}
Successful response output object
Name Type Description Example
code integer HTTP response code 200
result string Internal response ok
message string Human readable message explaining the response ✅ Successfully launched report
id string Report unique identifier zeoNSzmtEBxJSofisYWt
Example cURL
curl -X POST -H "X-api-key: API_KEY" -H "Content-Type: application/json" \
https://myreportgw.alaba.ai/v1/create_and_launch 
# replace API_KEY with yours
Example response
{
    "code": 200,
    "result": "ok",
    "message": "Successfully launched report",
    "id": "zeoNSzmtEBxJSofisYWt"
}

Relaunch an existing report

POST /relaunch

Allows users to relaunch a report with modifications based on a relaunch reason.

Parameters
Name Type Default value Description
id string None Unique identifier of the report to be relaunched.
relaunch_reason string ['bad_content', 'bad_writing', 'bad_references', 'bad_images_or_tables', 'no_analysis', 'my_bad', 'versioning', 'feeling_lucky', 'bad_translation', 'other'] None Reason for relaunching the report, accepted values are: “bad_content” (the content is not what I ordered), “bad_writing” (poor writing skills), “bad_references” (wrong or incomplete references found), “bad_images_or_tables” (the images or tables are erroneous), “no_analysis” (no data analysis or reasoning), “my_bad” (I forgot some details to ask for), “versioning” (I need several versions of it), “feeling_lucky” (I am just trying if it improves), “bad_translation” (language has grammatical errors), “other” (other).
title string minLength=1 maxLength=200 None Optional. New title for the relaunched report (use the report previous value if not present).
description string minLength=60 maxLength=800 None Optional. New detailed description for the relaunched report (use the report previous value if not present).
additional_indications string maxLength=1000 Optional. Additional instructions for the relaunch (use the report previous value if not present).
citations_format string ['IEEE', 'APA', 'MLA'] IEEE Optional. New citation style (use the report previous value if not present).
inlined_citations boolean False Optional. Whether citations should be inline (use the report previous value if not present).
creative_analysis boolean False Optional. Enable creative analysis (use the report previous value if not present).
www_search boolean True Optional. Enable web search (use the report previous value if not present).
sites_to_search array [] Optional. List of specific domains to use in the search instead of the whole WWW (use the report previous value if not present).
sites_to_avoid array [] Optional. List of domains to avoid in search (use the report previous value if not present).
links_to_collect array [] Optional. Specific URLs to collect information from (use the report previous value if not present).
shared_drive_link string Optional. Google Drive folder or file link for private document sources (use the report previous value if not present).
Responses
Code Content-Type Description Example
200 application/json Successfully relaunched report {'code': 200, 'result': 'ok', 'message': '✅ Successfully relaunched report', 'id': 'zeoNSzmtEBxJSofisYWt'}
404 application/json Report not found {'code': 404, 'result': 'not-found', 'message': "❗ Report id 'zeoNSzmtEBxJSofisYWt' not found"}
400 application/json Bad request due to invalid input {'code': 400, 'result': 'invalid-argument', 'message': "❗ Invalid field value 'XXX' for [citations_format], it should be one of : 'IEEE', 'APA', 'MLA'"}
401 application/json Unauthorized request {'code': 401, 'result': 'unauthorized', 'message': '❗ Unauthorized'}
402 application/json No available plan {'code': 403, 'result': 'permission-denied', 'message': '❗ No available subscribed plan with remaining credit to execute this report'}
412 application/json Precondition failed {'code': 412, 'result': 'precondition-failed', 'message': '❗ No access to shared drive link, please grant view permissions to googledrive@myreport-2022.iam.gserviceaccount.com'}
409 application/json Free queue is full (when using a free plan), please retry later {'code': 429, 'result': 'resource-exhausted', 'message': '⚠️ Overload for free queue'}
429 application/json Too many reports in execution {'code': 409, 'result': 'already-exists', 'message': '⚠️ Too many concurrent reports (max=1)'}
420 application/json Temporary failure {'code': 420, 'result': 'unknown', 'message': '❗ Unknown failure'}
500 application/json Internal server error {'code': 500, 'result': 'internal', 'message': 'Server unavailable'}
Successful response output object
Name Type Description Example
code integer HTTP response code 200
result string Internal response ok
message string Human readable message explaining the response ✅ Successfully relaunched report
id string Report unique identifier zeoNSzmtEBxJSofisYWt
Example cURL
curl -X POST -H "X-api-key: API_KEY" -H "Content-Type: application/json" \
https://myreportgw.alaba.ai/v1/relaunch 
# replace API_KEY with yours
Example response
{
    "code": 200,
    "result": "ok",
    "message": "Successfully relaunched report",
    "id": "zeoNSzmtEBxJSofisYWt"
}

Retrieve recent finished reports

GET /recent_finished_reports

Returns a list of reports that were completed within the specified number of hours.

Parameters
Name Type Default value Description
hours_ago integer minValue=1 1 Optional. A positive integer specifying the maximum number of hours since the reports were finished.
Responses
Code Content-Type Description Example
200 application/json A list of recently finished reports. [{'title': 'Analysis of the evolution of Gas Consumption in the World in the period 2000-2022', 'link': 'https://docs.google.com/document/d/1TuGDpEkpegDbfuncz1vL-VL-KFt-3xM2fyAmJ4PViPY', 'sources_link': 'https://docs.google.com/document/d/1rXA3zLob4966x6xikiuUYcfVqi2dNEn91BFtV_std-A', 'id': 'JF63wSuKghj7s20ZBZSp', 'finished_at': '2025-03-20T09:12:28Z'}]
400 application/json Invalid ‘hours_ago’ parameter. Must be a positive integer. {'code': 400, 'result': 'invalid-argument', 'message': "❗ Invalid field value '-10' for [hours_ago], it should be a positive integer greater than zero, representing the upper limit of hours elapsed since a report's completion to include it in the filtered results"}
401 application/json Unauthorized request {'code': 401, 'result': 'unauthorized', 'message': '❗ Unauthorized'}
420 application/json Temporary failure {'code': 420, 'result': 'unknown', 'message': '❗ Unknown failure'}
500 application/json Internal server error {'code': 500, 'result': 'internal', 'message': 'Server unavailable'}
Successful response output object

Every object in the response array has these fields:

Name Type Description Example
title string Title of the report Analysis of the evolution of Gas Consumption in the World in the period 2000-2022
link string Link to the report document in Google Drive https://docs.google.com/document/d/1TuGDpEkpegDbfuncz1vL-VL-KFt-3xM2fyAmJ4PViPY
sources_link string Link to the sources management information document in Google Drive https://docs.google.com/document/d/1rXA3zLob4966x6xikiuUYcfVqi2dNEn91BFtV_std-A
id string Unique identifier for the report JF63wSuKghj7s20ZBZSp
finished_at string Timestamp when the report was completed (UTC) 2025-03-20T09:12:28Z
Example cURL
curl -X GET -H "X-api-key: API_KEY" -H "Content-Type: application/json" \
https://myreportgw.alaba.ai/v1/recent_finished_reports?hours_ago=1 
# replace API_KEY with yours
Example response
[
{
    "title": "Analysis of the evolution of Gas Consumption in the World in the period 2000-2022",
    "link": "https://docs.google.com/document/d/1TuGDpEkpegDbfuncz1vL-VL-KFt-3xM2fyAmJ4PViPY",
    "sources_link": "https://docs.google.com/document/d/1rXA3zLob4966x6xikiuUYcfVqi2dNEn91BFtV_std-A",
    "id": "JF63wSuKghj7s20ZBZSp",
    "finished_at": "2025-03-20T09:12:28Z"
}
]

Retrieve recent failed reports

GET /recent_failed_reports

Returns a list of reports that were launched but unfortunately failed within the specified number of hours.

Parameters
Name Type Default value Description
hours_ago integer minValue=1 1 Optional. A positive integer specifying the maximum number of hours since the report failure.
Responses
Code Content-Type Description Example
200 application/json A list of recently failed reports. [{'title': 'Analysis of the evolution of Gas Consumption in the World in the period 2000-2022', 'sources_link': 'https://docs.google.com/document/d/1rXA3zLob4966x6xikiuUYcfVqi2dNEn91BFtV_std-A', 'id': 'JF63wSuKghj7s20ZBZSp', 'failure_reason': 'not enough data was found to fill the report with this size', 'failed_at': '2025-03-20T09:12:28Z'}]
400 application/json Invalid ‘hours_ago’ parameter. Must be a positive integer. {'code': 400, 'result': 'invalid-argument', 'message': "❗ Invalid field value '-10' for [hours_ago], it should be a positive integer greater than zero, representing the upper limit of hours elapsed since a report's completion to include it in the filtered results"}
401 application/json Unauthorized request {'code': 401, 'result': 'unauthorized', 'message': '❗ Unauthorized'}
420 application/json Temporary failure {'code': 420, 'result': 'unknown', 'message': '❗ Unknown failure'}
500 application/json Internal server error {'code': 500, 'result': 'internal', 'message': 'Server unavailable'}
Successful response output object

Every object in the response array has these fields:

Name Type Description Example
title string Title of the report Analysis of the evolution of Gas Consumption in the World in the period 2000-2022
sources_link string Optional. Link to the sources management information document in Google Drive https://docs.google.com/document/d/1rXA3zLob4966x6xikiuUYcfVqi2dNEn91BFtV_std-A
id string Unique identifier for the report JF63wSuKghj7s20ZBZSp
failure_reason string Reason for the report to be failed not enough data was found to fill the report with this size
failed_at string Timestamp when the report was failed (UTC) 2025-03-20T09:12:28Z
Example cURL
curl -X GET -H "X-api-key: API_KEY" -H "Content-Type: application/json" \
https://myreportgw.alaba.ai/v1/recent_failed_reports?hours_ago=1
# replace API_KEY with yours
Example response
[
{
    "title": "Analysis of the evolution of Gas Consumption in the World in the period 2000-2022",
    "sources_link": "https://docs.google.com/document/d/1rXA3zLob4966x6xikiuUYcfVqi2dNEn91BFtV_std-A",
    "id": "JF63wSuKghj7s20ZBZSp",
    "failure_reason": "not enough data was found to fill the report with this size",
    "failed_at": "2025-03-20T09:12:28Z"
}
]

Get API report launch credits

GET /api_credit

Returns the available credits for API-based report launches. Each credit allows launching one report, while relaunching a report does not consume additional credits.

Parameters

None

Responses
Code Content-Type Description Example
200 application/json Successful response with available credit details. {'code': 200, 'message': 'Credits retrieved successfully', 'available_credits': 5}
401 application/json Unauthorized request {'code': 401, 'result': 'unauthorized', 'message': '❗ Unauthorized'}
420 application/json Temporary failure {'code': 420, 'result': 'unknown', 'message': '❗ Unknown failure'}
500 application/json Internal server error {'code': 500, 'result': 'internal', 'message': 'Server unavailable'}
Successful response output object
Name Type Description Example
code integer HTTP response code 200
message string Human readable message explaining the response Credits retrieved successfully
available_credits integer Remaining credits for new report launches 5
Example cURL
curl -X GET -H "X-api-key: API_KEY" -H "Content-Type: application/json" \
https://myreportgw.alaba.ai/v1/api_credit 
# replace API_KEY with yours
Example response
{
    "code": 200,
    "message": "Credits retrieved successfully",
    "available_credits": 5
}

Thank you for your interest, it encourages us to improve day by day.
alaba a.i.

Save Your Time Now

You are a click away of generating automated reports!

Try it for Free

2022 AiAlaba © all rights reserved.