# HTTP API

Base path: `/market/mk20`\
`{id}` is the deal identifier (ULID).

## Authentication

All Market 2.0 API routes require auth except `/info/*`.

Auth details are documented in: [Architecture: Authentication and Authorization](/market-2.0/architecture.md#authentication-and-authorization)

## API Compatibility

Market 2.0 APIs are expected to evolve conservatively, with backward compatibility as a primary consideration.

## Swagger and OpenAPI Specs

Use the running storage provider spec first for integration and debugging.

Running provider endpoints:

1. `GET /market/mk20/info/`
2. `GET /market/mk20/info/swagger.yaml`
3. `GET /market/mk20/info/swagger.json`

Source tree specs:

1. [`market/mk20/http/swagger.yaml`](https://github.com/filecoin-project/curio/blob/main/market/mk20/http/swagger.yaml)
2. [`market/mk20/http/swagger.json`](https://github.com/filecoin-project/curio/blob/main/market/mk20/http/swagger.json)

Version note:

1. A running provider may be on a different Curio version than this documentation.
2. If behavior differs, use that provider's `/info/swagger.*` as the operational reference.

## Endpoint Map

1. `POST /deal`
2. `GET /status/{id}`
3. `POST /update/{id}`
4. `GET /products`
5. `GET /sources`
6. `GET /contracts`
7. `POST /uploads/{id}`
8. `GET /uploads/{id}`
9. `PUT /uploads/{id}/{chunkNum}`
10. `POST /uploads/finalize/{id}`
11. `PUT /upload/{id}`
12. `POST /upload/{id}`

## Endpoint Details

## `POST /deal`

Creates a deal.

Request:

1. Body: `mk20.Deal` JSON.

Success:

1. `200` `Ok`

Error codes:

1. `400` `ErrBadProposal`
2. `401` `ErrUnAuthorized`
3. `404` `ErrDealNotFound`
4. `422` `ErrUnsupportedDataSource`
5. `423` `ErrUnsupportedProduct`
6. `424` `ErrProductNotEnabled`
7. `425` `ErrProductValidationFailed`
8. `426` `ErrDealRejectedByMarket`
9. `429` `ErrServiceOverloaded`
10. `430` `ErrMalformedDataSource`
11. `440` `ErrMarketNotEnabled`
12. `441` `ErrDurationTooShort`
13. `500` `ErrServerInternalError`
14. `503` `ErrServiceMaintenance`

Response note:

1. Error body is plain text: `Reason: <text>`.

## `GET /status/{id}`

Returns deal status by product.

Success:

1. `200` `mk20.DealProductStatusResponse`

Error codes:

1. `400` invalid/missing id
2. `401` `ErrUnAuthorized`
3. `404` `ErrDealNotFound`
4. `500` `ErrServerInternalError`

## `POST /update/{id}`

Updates an existing deal in supported update paths. The update path can fill missing `data` or add product fields that are not already present. Existing `data` and existing product fields are not replaced.

Request:

1. Body: `mk20.Deal` JSON.

Success:

1. `200` `Ok`

Error codes:

1. `400` `ErrBadProposal`
2. `401` `ErrUnAuthorized`
3. `404` `ErrDealNotFound`
4. `422` `ErrUnsupportedDataSource`
5. `423` `ErrUnsupportedProduct`
6. `424` `ErrProductNotEnabled`
7. `425` `ErrProductValidationFailed`
8. `426` `ErrDealRejectedByMarket`
9. `429` `ErrServiceOverloaded`
10. `430` `ErrMalformedDataSource`
11. `440` `ErrMarketNotEnabled`
12. `441` `ErrDurationTooShort`
13. `500` `ErrServerInternalError`
14. `503` `ErrServiceMaintenance`

## `GET /products`

Returns enabled products for this provider.

Success:

1. `200` `{ "products": [...] }`

Error codes:

1. `401` `ErrUnAuthorized`
2. `500` `ErrServerInternalError`

## `GET /sources`

Returns enabled data source types for this provider.

Success:

1. `200` `{ "sources": [...] }`

Error codes:

1. `401` `ErrUnAuthorized`
2. `500` `ErrServerInternalError`

## `GET /contracts`

Returns allowlisted DDO market contracts for this provider.

Success:

1. `200` `{ "contracts": [...] }`

Error codes:

1. `401` `ErrUnAuthorized`
2. `404` no supported contracts found
3. `500` `ErrServerInternalError`

## `POST /uploads/{id}`

Starts chunked upload session.

Request:

1. Body: `StartUpload` (`raw_size`, `chunk_size`).

Success:

1. `200` `UploadStartCodeOk`

Error codes:

1. `400` `UploadStartCodeBadRequest`
2. `401` `ErrUnAuthorized`
3. `404` `UploadStartCodeDealNotFound`
4. `409` `UploadStartCodeAlreadyStarted`
5. `500` `UploadStartCodeServerError`

## `GET /uploads/{id}`

Returns chunked upload progress.

Success:

1. `200` `UploadStatusCodeOk`

Error codes:

1. `400` invalid/missing id
2. `401` `ErrUnAuthorized`
3. `404` `UploadStatusCodeDealNotFound`
4. `425` `UploadStatusCodeUploadNotStarted`
5. `500` `UploadStatusCodeServerError`

## `PUT /uploads/{id}/{chunkNum}`

Uploads one chunk.

Success:

1. `200` `UploadOk`

Error codes:

1. `400` `UploadBadRequest`
2. `401` `ErrUnAuthorized`
3. `404` `UploadNotFound`
4. `409` `UploadChunkAlreadyUploaded`
5. `429` `UploadRateLimit`
6. `500` `UploadServerError`

## `POST /uploads/finalize/{id}`

Finalizes chunked upload. Body may be empty or full `mk20.Deal`.

Success:

1. `200` `Ok`

Error codes:

1. `400` `ErrBadProposal`
2. `401` `ErrUnAuthorized`
3. `404` `ErrDealNotFound`
4. `422` `ErrUnsupportedDataSource`
5. `423` `ErrUnsupportedProduct`
6. `424` `ErrProductNotEnabled`
7. `425` `ErrProductValidationFailed`
8. `426` `ErrDealRejectedByMarket`
9. `429` `ErrServiceOverloaded`
10. `430` `ErrMalformedDataSource`
11. `440` `ErrMarketNotEnabled`
12. `441` `ErrDurationTooShort`
13. `500` `ErrServerInternalError`
14. `503` `ErrServiceMaintenance`

## `PUT /upload/{id}`

Uploads full payload in serial flow.

Success:

1. `200` `UploadOk`

Error codes:

1. `400` `UploadBadRequest`
2. `401` `ErrUnAuthorized`
3. `404` `UploadStartCodeDealNotFound`
4. `500` `UploadServerError`

## `POST /upload/{id}`

Finalizes serial upload. Body may be empty or full `mk20.Deal`.

Success:

1. `200` `Ok`

Error codes:

1. `400` `ErrBadProposal`
2. `401` `ErrUnAuthorized`
3. `404` `ErrDealNotFound`
4. `422` `ErrUnsupportedDataSource`
5. `423` `ErrUnsupportedProduct`
6. `424` `ErrProductNotEnabled`
7. `425` `ErrProductValidationFailed`
8. `426` `ErrDealRejectedByMarket`
9. `429` `ErrServiceOverloaded`
10. `430` `ErrMalformedDataSource`
11. `440` `ErrMarketNotEnabled`
12. `441` `ErrDurationTooShort`
13. `500` `ErrServerInternalError`
14. `503` `ErrServiceMaintenance`

## Operational Notes

1. Upload finalize endpoints accept an empty body when the deal already has data details. If the accepted deal omitted data details, finalize must include a full deal payload so MK20 can bind the uploaded piece to the deal.
2. Provider policies for products, sources, and contracts affect acceptance behavior.
3. When behavior differs from docs, trust the running provider `/info/swagger.*`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.curiostorage.org/market-2.0/http-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.