Documentation menu
Docs / Developers / Files and jobs

Files and jobs

Upload a file to create or replace a layer, export a GeoPackage, and follow the background job until it finishes.

Upload a file and create a layer#

  1. Request an upload URL

    Send POST /v1/uploads with the filename, byte size and content type, as below. Use a read_write key on a role that can create content. The response contains uploadId, url, expiresAt and maxBytes.

  2. Upload the bytes

    PUT the file to url with the same Content-Type. The signed URL is the credential; do not add your OrbGIS bearer header. Upload before expiresAt.

  3. Create the collection

    Send POST /v1/collections with uploadId, title, layerName and itemType, as below. Add sourceLayer for a multi-layer file, sourceSrid when needed, or csv with latColumn and lonColumn for CSV coordinates.

  4. Wait for completion

    The response is 202 with job. Poll GET /v1/jobs/{id} or use job webhooks. Continue while job.status is queued or running; stop at done, failed or cancelled. On success, job.result identifies the item and collection.

Example body for POST /v1/uploads:

{"filename": "roads.gpkg", "size": 1048576, "contentType": "application/geopackage+sqlite3"}

Use your file’s actual size. Example body for POST /v1/collections, using the returned upload id:

{"uploadId": "UPLOAD_ID_FROM_UPLOAD_RESPONSE", "title": "Roads", "layerName": "roads", "itemType": "feature_service"}
Note

The default API upload limit is 50 MiB. Check maxBytes; a file above the configured cap returns 413 upload_too_large. Supported formats include GeoPackage, zipped Shapefile, GeoJSON and CSV; see Uploading data for format requirements.

Tip

Retrying collection creation with the same uploadId returns the existing job with 200 and does not create a duplicate layer. If the upload URL expires before the file is sent, request a new URL.

Read or cancel a job#

Job responses use a job wrapper. Read job.status, job.phase, job.progress, job.error and job.result. Jobs are visible only to the integration or person that started them. POST /v1/jobs/{id}/cancel requests cancellation of a queued or running ingest job.

Export a layer#

Send POST /v1/collections/{id}/export with {"format":"gpkg"} and a read_write key. Poll the returned job. When job.status is done, download from job.result.downloadUrl; on failed or cancelled, inspect job.error instead.

The signed download URL lasts ten minutes and is renewed on each job read. The file contains all attributes and objectids in the storage coordinate system and is retained for seven days. Only GeoPackage export is currently supported.

One export can be active per integration. Another export request while one is queued or running returns that active job with 200; check its collection before using the result.

Keep a dataset in sync#

Create the collection on the first run and save its collectionId. On later runs, upload a new file and call /v1/collections/{id}/replace. The id, styling and map references stay the same. See Writing features for replacement and row-level changes.