Skip to content

Commit

Permalink
add TOC and fix heading levels
Browse files Browse the repository at this point in the history
  • Loading branch information
zeke committed Aug 30, 2023
1 parent e50bfc8 commit 1b8c5c7
Showing 1 changed file with 19 additions and 6 deletions.
25 changes: 19 additions & 6 deletions docs/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,19 @@

When a Cog Docker image is run, it serves an HTTP API for making predictions. For more information, take a look at [the documentation for deploying models](deploy.md).

## Contents

- [Running the server](#running-the-server)
- [Stopping the server](#stopping-the-server)
- [API](#api)
- [`GET /openapi.json`](#get-openapijson)
- [`POST /predictions` (synchronous)](#post-predictions-synchronous)
- [`POST /predictions` (asynchronous)](#post-predictions-asynchronous)
- [Webhooks](#webhooks)
- [`PUT /predictions/` (synchronous)](#put-predictions-synchronous)
- [`PUT /predictions/` (asynchronous)](#put-predictions-asynchronous)
- [`POST /predictions/{prediction_id}/cancel`](#post-predictionscancel)

## Running the server

First, build your model:
Expand Down Expand Up @@ -45,7 +58,7 @@ docker kill my-model

The [OpenAPI](https://swagger.io/specification/) specification of the API, which is derived from the input and output types specified in your model's [Predictor](python.md) and [Training](training.md) objects.

## `POST /predictions` (synchronous)
### `POST /predictions` (synchronous)

Make a single prediction. The request body should be a JSON object with the following fields:

Expand Down Expand Up @@ -88,7 +101,7 @@ Or, with curl:

curl -X POST -H "Content-Type: application/json" -d '{"input": {"image": "https://example.com/image.jpg", "text": "Hello world!"}}' http://localhost:5000/predictions

## `POST /predictions` (asynchronous)
### `POST /predictions` (asynchronous)

Make a single prediction without waiting for the prediction to complete.

Expand Down Expand Up @@ -124,7 +137,7 @@ using the provided `--upload-url` as a prefix, in much the same way that
works the same way for both synchronous and asynchronous prediction creation.
This will be addressed in a future version of Cog.

### Webhooks
#### Webhooks

Clients can (and should, if a prediction is created asynchronously) provide a
`webhook` parameter at the top level of the prediction request, e.g.
Expand Down Expand Up @@ -170,7 +183,7 @@ Prefer: respond-async
}
```

## `PUT /predictions/<prediction_id>` (synchronous)
### `PUT /predictions/<prediction_id>` (synchronous)

Make a single prediction.

Expand All @@ -184,7 +197,7 @@ supplied prediction ID is unique. We recommend you use base32-encoded UUID4s
(stripped of any padding characters) to ensure forward compatibility: these will
be 26 ASCII characters long.

## `PUT /predictions/<prediction_id>` (asynchronous)
### `PUT /predictions/<prediction_id>` (asynchronous)

Make a single prediction without waiting for the prediction to complete.

Expand All @@ -208,7 +221,7 @@ be 26 ASCII characters long.
the caller's responsibility to make sure that earlier predictions are complete
before new ones (with new IDs) are created.

## `POST /predictions/<prediction_id>/cancel`
### `POST /predictions/<prediction_id>/cancel`

While an asynchronous prediction is running, clients can cancel it by making a
request to `POST /predictions/<prediction_id>/cancel`. The prediction `id` must
Expand Down

0 comments on commit 1b8c5c7

Please sign in to comment.