NAV Navbar
shell
  • Introduction
  • Authentication
  • Recipes
  • Task Batches
  • Tasks
  • Introduction

    A complete API reference for Apres, a library made to enable the easy integration of Solutions and Recipes into your application and data infrastructure.

    API Endpoint
    https://api.apres.io/api/v1
    

    Overview

    Apres is a platform for creating active learning training automations. The API supports interacting with your automations (Recipes) once they have been created through your Dashboard. The API focuses on processing data tasks from the comfort of your terminal.

    Having created the Recipe through the Canvas, the API will let you:

    Each Recipe is designed to operate on a single Recipe and expects to have the Recipe's API Key included in the Authorization Header for the API Request. A Recipe-level API Key allows for the possibility of federated access and processing of individual Recipes by your team or your partners.

    Authentication

    To authorize, use this code:

    curl -H "Authorization: <RECIPE_API_KEY> /recipes/:recipe_id
    

    Make sure to replace <RECIPE_API_KEY> with your Recipe's API key.

    Apres uses Recipe-level API keys to allow access to the API.

    Once you have defined a Recipe through the Apres Interface, an API Key is automatically created for the Recipe. No additional setup is required, and your Recipe is immediately available for API-based interaction

    Apres expects for the API key to be included in all API requests to the server in a header that looks like the following:
    Authorization: <RECIPE_API_KEY>.

    Recipes

    Get Recipe Details

    curl "/recipe"
      -H "Authorization: RECIPE_API_KEY"
    

    Response

    {
        "id": "2b5a3e3c-65d7-11e9-9d46-60f81dab267a",
        "name": "Image Classification Tester",
        "status": "Enabled",
        "created_at": "2018-10-27T21:36:50.000Z",
        "updated_at": "2018-10-27T21:36:50.000Z",
        "processing_templates": [
            {
                "id": 116,
                "sequence": 1,
                "type": "CategorisationTemplate",
                "instruction": "Is this a wading bird?",
                "choices": ["Yes", "No"],
                "multiple_choices": false,
                "options": null
            }
        ]
    }
    

    This endpoint retrieves information for a specific recipe. The Apres platform uniquely identifies your RECIPE API KEY in the Authorization header with your Recipe, so no additional parameters are required.

    HTTP Request

    GET /recipe

    Error Codes
    Error Code Meaning
    401 Unauthorized request for recipe

    Load a Processed Task Batch for a Recipe

    curl -X POST "/recipe/load_batch"
      -H "Authorization: RECIPE_API_KEY"
      -d '{
            "file": "set1.csv",
            "data": "/9j/4AAQSkZJRgABAQEASABIAAD//gAjY21w...",
            "golden_set": true
    
          }'
    

    Response:

    {
        "message": "Your processed batch is being loaded"
    }
    

    This Endpoint can be used to load a processed Task Batch with results for a Recipe. Use this with golden_set set to true to load a Golden Set for your Recipe, which will be used to inform and train Experts and in training an Active Learning model. This can also be used without the golden_set parameter to provide more training data for any Active Learning models supporting the Recipe.

    The format of the file should be a Base64-encoded CSV with
    For Example
    Input Type Output
    https://s3.us-west-... image/jpeg Heron
    https://s3.us-west-... image/jpeg Bird
    HTTP Request

    POST /recipe/load_batch

    Parameters
    Parameter Description
    file Name of the File supplied (required)
    data Base64 encoded contents of the File (required)
    golden_set true/false Boolean (optional)
    Error Codes
    Error Code Meaning
    401 Unauthorized request for recipe
    422 A Golden Set already exists for this Recipe

    Task Batches

    Create a new Task Batch for a Recipe. There are multiple payload options to create a new Task Batch.

    Task Batch

    {
        "id": "60649254-69b4-11e9-bef7-60f81dab267a",
        "created_at": "2019-04-28T12:51:44.000Z",
        "updated_at": "2019-04-28T12:51:44.000Z",
        "size": 0,
        "status": "Pending",
        "price": 0,
        "state": "confirmed",
        "estimated_size": 1,
        "estimated_data_points": 1,
        "slug": "characteristic-bug-photographed",
        "mode": "default",
        "delivery_timeframe": 7,
        "delivery_units": "days",
        "sandbox": false
    }
    

    This request will guarantee receipt of the payload via an HTTP 201 status along with an estimated task size. The actual Tasks from the payload will be generated asynchronously, so while the immediate response of size is 0, the estimated_size will represent a non-zero initial assessment of Tasks to be generated in the Task Batch.

    Typically most Task Batches will have three state changes delivered to your webhook.

    The webhook payload is a JSON object with a two key elements, a state and a message in addition to the Recipe and Task Batch identifiers.

    POST a Task Batch

    POST a Base64 file

    curl -X POST "/task_batches"
      -H "Authorization: RECIPE_API_KEY"
      -d '{
            "files": [
                {
                    "file": "file1.jpg",
                    "data": "/9j/4AAQSkZJRgABAQEASABIAAD//gAjY21w..."
                }
            ]
            "delivery_timeframe": 7,
            "delivery_units": "days
    
          }'
    

    POST an Amazon S3 Bucket

    curl -X POST "/task_batches"
      -H "Authorization: RECIPE_API_KEY"
      -d '{
            "location": {
                "type": "s3",
                "bucket_name": "task-test.apres.io",
                "region": "us-west-1",
                "prefix": "birds/"
            }
        }'
    

    POST an Azure Blob

    curl -X POST "/task_batches"
      -H "Authorization: RECIPE_API_KEY"
      -d '{
            "location": {
                "type": "azure-blob",
                "blob_endpoint": "https://apresio.blob.core.windows.net",
                "container": "task-test",
                "sas_token": "?sv=2017-11-09&ss=b&srt=co&sp=rl&se=2018-08-25T06:14:26Z&st=2018-08-17T22:14:26Z&spr=https&sig=FQis5WBA8DmDYWnQspJd1j1FmqBqv1HA7fBUol%2FUwqY%3D"
            },
            "webhook_url": "https://notify-me-of-batch-status.com"
        }'
    
    
    HTTP Request

    POST /task_batches

    Prameters

    Here is a list of the JSON parameters that can be passed in:

    Parameter Description
    delivery_timeframe Optional 1 or 7
    delivery_units Optional "days"
    webhook_url Optional Fully qualified notification URL for state changes

    File Upload Parameters

    Parameter Description
    files The array of files in the Task Batch
    Each element of the files array has the following fields:
    Parameter Description
    file The name of the file being processed
    data The Base64 data representing the file contents for processing
    Location-based Payload Parameters
    Parameter Description
    location Hash containing Location Details
    location["type"] One of "s3" or "azure-blob" required
    location["bucket_name] Required Name of S3 bucket if type s3
    location["region"] Required Valid AWS Region of S3 bucket if type s3
    location["prefix"] Optional Prefix within Bucket if type s3
    location["blob_endpoint] Required Blob Endpoint String if type azure-blob
    location["container"] Required Container String if type azure-blob
    location["sas_token"] Required Sas Token String if type azure-blob

    GET Task Batches for a Recipe

    curl "/task_batches"
      -H "Authorization: RECIPE_API_KEY"
    

    Receive an array of batches

    [
        {
            "id": "45b000fa-65d7-11e9-9d46-60f81dab267a",
            "created_at": "2019-04-23T14:51:27.000Z",
            "updated_at": "2019-04-23T14:51:27.000Z",
            "size": 0,
            "status": "Pending",
            "price": 0,
            "state": "created",
            "estimated_size": 7,
            "estimated_data_points": 7,
            "slug": "characteristic-bug-updated",
            "mode": "default",
            "delivery_timeframe": 7,
            "delivery_units": "days",
            "sandbox": false
        }
    ]
    

    This endpoint retrieves information for all the Task Batches generated for a Recipe.

    HTTP Request

    GET /task_batches

    Parameters
    Parameter Description
    Error Codes
    Error Code Meaning
    401 Unauthorized request

    Get a Specific Task Batch for a Recipe

    curl "/task_batches/962ac070-da30-11e8-965c-60f81dab267a"
      -H "Authorization: RECIPE_API_KEY"
    
    {
        "id": "a7437932-65d7-11e9-9d46-60f81dab267a",
        "created_at": "2019-04-23T14:54:11.000Z",
        "updated_at": "2019-04-23T14:57:11.000Z",
        "size": 7,
        "status": "Completed",
        "price": 0.28,
        "state": "completed",
        "estimated_size": 7,
        "estimated_data_points": 7,
        "slug": "characteristic-bug-stretched",
        "mode": "default",
        "delivery_timeframe": 7,
        "delivery_units": "days",
        "sandbox": false
    }
    

    This endpoint retrieves information for a specific Task Batch generated for a Recipe.

    HTTP Request

    GET /task_batches/<ID>

    Parameters
    Parameter Description
    ID The ID of the Task Batch
    Error Codes
    Error Code Meaning
    401 Unauthorized request for recipe
    404 There is no Recipe or Task Batch with the provided ID
    Get the Output of a specific Task Batch for a Recipe
    curl "/task_batches/962ac070-da30-11e8-965c-60f81dab267a/output"
      -H "Authorization: RECIPE_API_KEY"
    
    {
        "json": [
            {
                "task_id": "ab649ef6-65d7-11e9-8cc6-60f81dab267a",
                "input": "https://s3.us-west-2.amazonaws.com/partners.apres.io/data_in/2b5a3e3c-65d7-11e9-9d46-60f81dab267a/2019-04-23T14%3A50%3A56.716Z/2161962975_128cb5ddbd_m.jpg",
                "output": ["Waterfowl"],
                "status": "Completed",
                "consensus_score": 0
            },
            {
                "task_id": "ab6d45c4-65d7-11e9-8cc6-60f81dab267a",
                "input": "https://s3.us-west-2.amazonaws.com/partners.apres.io/data_in/2b5a3e3c-65d7-11e9-9d46-60f81dab267a/2019-04-23T14%3A50%3A56.716Z/2162765054_840fbf7acf_m.jpg",
                "output": ["Waterfowl"],
                "status": "Completed",
                "consensus_score": 0
            }
        ],
        "csv": "https://s3.us-west-2.amazonaws.com/partners.apres.io/data_out/2b5a3e3c-65d7-11e9-9d46-60f81dab267a/task_batches/a7437932-65d7-11e9-9d46-60f81dab267a/output.csv",
        "statistics": [
            {
                "name": "Successful Tasks",
                "value": 2
            },
            {
                "name": "Failed Tasks",
                "value": 0
            },
            {
                "name": "Elapsed Time",
                "value": 180
            },
            {
                "name": "Elapsed Time (in words)",
                "value": "3 minutes"
            },
            {
                "name": "Time to Start Processing Tasks",
                "value": 152
            },
            {
                "name": "Average Processing Time",
                "value": 3.14
            },
            {
                "name": "Tasks with Expert Consensus",
                "value": 0
            },
            {
                "name": "Tasks without Expert Consensus",
                "value": 0
            },
            {
                "name": "Time to First Results",
                "value": 174
            }
        ]
    }
    

    This Endpoint retrieves the output of a Task Batch in both json and csv form and includes relevant statistics for the Batch.

    HTTP Request

    GET /task_batches/<ID>/output

    Parameters
    Parameter Description
    ID The ID of the Task Batch
    Error Codes
    Error Code Meaning
    401 Unauthorized request for recipe
    404 There is no Recipe or Task Batch with the provided ID

    Tasks

    Get Tasks for a Task Batch

    curl "/task_batches/a7437932-65d7-11e9-9d46-60f81dab267a/tasks"
      -H "Authorization: RECIPE_API_KEY"
    
    [
        {
            "id": "ab649ef6-65d7-11e9-8cc6-60f81dab267a",
            "status": "Completed",
            "created_at": "2019-04-23T14:54:17.000Z",
            "updated_at": "2019-04-23T14:56:59.000Z",
            "input": "2161962975_128cb5ddbd_m.jpg",
            "output": ["Waterfowl"],
            "feedback": null,
            "state": "completed",
            "input_type": "image",
            "consensus_score": 0,
            "responses_with_confidence": null
        },
        {
            "id": "ab6d45c4-65d7-11e9-8cc6-60f81dab267a",
            "status": "Completed",
            "created_at": "2019-04-23T14:54:17.000Z",
            "updated_at": "2019-04-23T14:57:00.000Z",
            "input": "2162765054_840fbf7acf_m.jpg",
            "output": ["Waterfowl"],
            "feedback": null,
            "state": "completed",
            "input_type": "image",
            "consensus_score": 0,
            "responses_with_confidence": null
        },
        {
            "id": "ab6e2e3a-65d7-11e9-8cc6-60f81dab267a",
            "status": "Completed",
            "created_at": "2019-04-23T14:54:18.000Z",
            "updated_at": "2019-04-23T14:57:02.000Z",
            "input": "2162775358_0b2a1f6cfb_m.jpg",
            "output": ["Heron"],
            "feedback": null,
            "state": "completed",
            "input_type": "image",
            "consensus_score": 0,
            "responses_with_confidence": null
        },
        {
            "id": "ab6edec0-65d7-11e9-8cc6-60f81dab267a",
            "status": "Completed",
            "created_at": "2019-04-23T14:54:18.000Z",
            "updated_at": "2019-04-23T14:57:04.000Z",
            "input": "2162780604_150cbe300b_m.jpg",
            "output": ["Bird"],
            "feedback": null,
            "state": "completed",
            "input_type": "image",
            "consensus_score": 0,
            "responses_with_confidence": null
        },
        {
            "id": "ab6f8820-65d7-11e9-8cc6-60f81dab267a",
            "status": "Completed",
            "created_at": "2019-04-23T14:54:18.000Z",
            "updated_at": "2019-04-23T14:57:06.000Z",
            "input": "2162788966_57639b1d5b_m.jpg",
            "output": ["Animal"],
            "feedback": null,
            "state": "completed",
            "input_type": "image",
            "consensus_score": 0,
            "responses_with_confidence": null
        },
        {
            "id": "ab70332e-65d7-11e9-8cc6-60f81dab267a",
            "status": "Completed",
            "created_at": "2019-04-23T14:54:18.000Z",
            "updated_at": "2019-04-23T14:57:08.000Z",
            "input": "2252807245_b87c757eac_m.jpg",
            "output": ["Crane Bird"],
            "feedback": null,
            "state": "completed",
            "input_type": "image",
            "consensus_score": 0,
            "responses_with_confidence": null
        },
        {
            "id": "ab70e062-65d7-11e9-8cc6-60f81dab267a",
            "status": "Completed",
            "created_at": "2019-04-23T14:54:18.000Z",
            "updated_at": "2019-04-23T14:57:10.000Z",
            "input": "2252820681_7696054ac0_m.jpg",
            "output": ["Waterfowl"],
            "feedback": null,
            "state": "completed",
            "input_type": "image",
            "consensus_score": 0,
            "responses_with_confidence": null
        }
    ]
    

    This endpoint retrieves details of Tasks for a Task Batch.

    HTTP Request

    GET /task_batches/<TaskBatchID>/tasks

    Parameters
    Parameter Description
    TaskBatchID Id of Task Batch
    Error Codes
    Error Code Meaning
    401 Unauthorized request
    404 Task Batch not found