> For the complete documentation index, see [llms.txt](https://docs.curiostorage.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.curiostorage.org/market-2.0/http-api.md).

# 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.*`.