Mint Asset URLs

POST

https://api.captain.dev/v3/collections/:collection_name/documents/:document_id/asset-urls

POST

/v3/collections/:collection_name/documents/:document_id/asset-urls

1 import json
2 import requests
3 
4 BASE_URL = "https://api.captain.dev"
5 API_KEY = "your_api_key"
6 COLLECTION_NAME = "research_library"
7 DOCUMENT_ID = "doc_climate_agriculture_2024"
8 
9 headers = {
10     "Authorization": f"Bearer {API_KEY}",
11     "Content-Type": "application/json",
12 }
13 
14 response = requests.post(
15     f"{BASE_URL}/v3/collections/{COLLECTION_NAME}/documents/{DOCUMENT_ID}/asset-urls",
16     headers=headers,
17     json={
18         "asset_ids": [
19             "fig_1_a2b3c4d5e6f7g2h3i4j5k6l7m2",
20             "fig_1_z7y6x5w4v3u2t7s6r5q4p3o2n7",
21         ],
22         "ttl_seconds": 1800,
23     },
24     timeout=30.0,
25 )
26 
27 print(json.dumps(response.json(), indent=2))

1 {
2   "collection_name": "research_library",
3   "document_id": "doc_climate_agriculture_2024",
4   "asset_urls": [
5     {
6       "asset_id": "fig_1_a2b3c4d5e6f7g2h3i4j5k6l7m2",
7       "status": "signed",
8       "bbox": {
9         "top": 0.12,
10         "left": 0.2,
11         "width": 0.5,
12         "height": 0.31
13       },
14       "content_type": "image/png",
15       "expires_at": "2024-05-21T08:30:00Z",
16       "image_url": "https://assets.captainusercontent.com/crops/org_1/doc_climate_agriculture_2024/p4-2.png?X-Amz-Expires=1800&X-Amz-Signature=REDACTED",
17       "kind": "figure",
18       "page": 4
19     },
20     {
21       "asset_id": "fig_1_z7y6x5w4v3u2t7s6r5q4p3o2n7",
22       "status": "unavailable",
23       "bbox": {
24         "top": 0.4,
25         "left": 0.15,
26         "width": 0.6,
27         "height": 0.22
28       },
29       "kind": "figure",
30       "message": "This document was indexed before figure cropping shipped, so no crop image exists. Re-index the document to generate crops.",
31       "page": 7,
32       "reason": "no_crop_available"
33     }
34   ],
35   "expires_at": "2024-05-21T08:30:00Z",
36   "expires_in_seconds": 1800,
37   "signed_count": 1,
38   "unavailable_count": 1,
39   "warnings": []
40 }

Mint short-lived presigned URLs for a document’s figure crops.

Supply the figure ids (regions[].figure_id) to mint URLs for. When batch requested, each item degrades on its own: a figure with no crop does not fail the whole request.

Path parameters

collection_namestringRequired

document_idstringRequired

Request

This endpoint expects an object.

asset_idslist of stringsRequired

Figure ids to mint URLs for, from regions[].figure_id. Stable and safe to store, unlike the URLs they mint. Up to 100; duplicates each return their own item.

ttl_secondsinteger or nullOptional60-604800

How long each URL stays valid, in seconds. Default 900 (15 min); min 60, max 604800 (7 days).

Response

Successful Response

collection_namestring

document_idstring

asset_urlslist of objectsOptional

expires_atstring or nullOptional

Earliest expiry across all signed items, so a client can schedule a single refresh instead of one timer per image. Null when nothing was signed.

expires_in_secondsinteger or nullOptional

Same deadline as a duration. Provided because browser clocks are routinely wrong, which makes an absolute-only expiry unreliable.

signed_countintegerOptionalDefaults to 0

unavailable_countintegerOptionalDefaults to 0

warningslist of stringsOptional

Errors

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error