Try in sandboxSign-in required · shared test environment
POST/api/upload_deployments/
Send JSON over HTTPS with your assigned api_key in the body. Use the appropriate test or production host.
Request body
DeploymentsUpload
Protocol requirements come from OpenAPI 0.4.1. Credentials are required for access. Gear submissions must also satisfy the required and conditional Data Rules, even where the test schema allows omissions.
| Field / type | Requirement | Description |
|---|---|---|
format_version number | Required | File Format Version, currently 0.3 |
api_key string · min length 32, max length 38 | Required for access | API credential. Keep credentials server-side and redact them from logs and support reports. |
sets array<Set> | Required | All gear deployments to be updated. View Set fields |
Required gear data
Manufacturer subscribers must supply required data for every set deployed using their devices.
Commercial subscriptions do not contribute data. Required fields must be supplied; conditional
fields must follow their stated rule, including explicit null values where specified.
- Use lowercase, 36-character UUID v4 identifiers.
- Use UTC timestamps in
YYYY-MM-DDThh:mm:ssZformat. - Field names and accepted values are case-sensitive. Submit coordinates at full available precision, at least five decimal places, without rounding.
- Submit updates promptly when a set’s status, position or conditions change.
Set
Submission requirements · Data Policy Appendix A.2
| Field / type | Requirement | Description |
|---|---|---|
vessel_id UUID v4 | Required | Assign once to the vessel and use the same ID for every submission from it. |
set_id UUID v4 | Required | Unique to this deployment. Reuse only to update this same set; assign a new ID when gear is deployed again. |
deployment_type string | Required | single: one trap. trawl: at least two traps connected by groundlines, with only the ends marked. line: a series of singles, each with its own gear mark. |
traps_in_set integer | Required | Use 1 for a single, the actual number of fishing traps for a trawl, or the number of traps in a line. |
trawl_path TrawlPath | null | Optional | GeoJSON LineString; follow the trawl path rules below. View TrawlPath fields |
share_with array<string> | null | Optional | Allowed destinations: PSMFC and Earth_Ranger. Name each separately. An empty selection excludes these destinations and Government Subscribers; ordinary permitted manufacturer sharing still applies. |
traps array<Trap> | Required | One object per marked gear unit, not per unmarked fishing trap in a trawl. View Trap fields |
fishery string | Required | Use a fishery name from the accepted values below, with exact case and underscores (Appendix A.5). Request additions through Polaris. |
permit_number string | Required | Fisher’s permit number, consistent with the issuing state or federal management entity’s format. |
fisher_name string | Required | Name of the fisher using the gear, in firstname lastname format. |
vessel_name string | Required | Name of the vessel using the gear, in vessel name format. |
when_updated_utc UTC timestamp | null | Read-only | Set by the server on upload. Omit from submissions; client values are ignored. |
Trap
One marked gear unit · Data Policy Appendix A.4
| Field / type | Requirement | Description |
|---|---|---|
trap_id UUID v4 | Required | Assign to the physical on-demand unit. If no unique unit exists, use a unique ID for that mark. For a trawl with a device on only one end, give the other end a separate ID. Reuse is allowed, but only one instance may be deployed at a time. |
sequence integer > 0 | Required | Single: 1. Trawl: 1 and 2 for the two ends. Line: number each mark in order starting at 1. Zero is not a valid submission value. |
latitude number, −90 to 90 | Required | Deployed latitude in decimal degrees. Submit full available precision, at least five decimal places; do not round. |
longitude number, −180 to 180 | Required | Deployed longitude in decimal degrees. Submit full available precision, at least five decimal places; do not round. |
deploy_datetime_utc UTC timestamp | Required | When the gear mark was deployed. |
surface_datetime_utc UTC timestamp | null | Conditional | Required for timed-release gear: when the buoy will surface. Set to null for gear without timed release. |
retrieved_datetime_utc UTC timestamp | null | Conditional | Required when gear is retrieved: the time of retrieval. |
status string | Required | deployed, retrieved or lost. Submit updates promptly when status changes. |
accuracy string | Required | GPS, acoustic or estimated (case-sensitive). |
release_type string | Required | acoustic, timed, other or none. Send explicitly, including none when there is no release. |
is_on_end boolean | Required | Whether this mark is on an end of the set. true for singles and both ends of a trawl. |
manufacturer string | null | Conditional | Required when the device’s serial number is used for fishing purposes, such as an on-demand release; otherwise null. Use the listed uppercase manufacturer code (Appendix A.6). |
model string | null | Conditional | Required under the same device condition as manufacturer; otherwise null. Use a model name or number consistently for that manufacturer. |
serial_number string | null | Conditional | Required under the same device condition as manufacturer; otherwise null. Supply the manufacturer’s serial number; the test schema limits it to 32 characters. |
Trawl paths
When supplying trawl_path, use a GeoJSON LineString with numeric [longitude, latitude] points. The first and last points must match the set’s first and
last trap locations. Update path points as the vessel moves; the recommended distance increment is 100
m.
If either end is retrieved, the entire set and its path are retrieved. Appendix A.3 specifies that a path whose endpoints no longer match the updated set positions is greyed out, with a straight dashed line between the trawl ends.
TrawlPath
| Field / type | Requirement | Description |
|---|---|---|
type string | Required by Data Rules | Must be LineString when a trawl_path is supplied. Default: "LineString" |
coordinates array<array<number>> | Required |
Accepted fishery names and manufacturer codes
Use the exact values in Appendix A.5–A.6. Request additions through Polaris for RMW approval. A manufacturer code does not establish an active integration.
Fishery names
- CA_Box_Crab
- CA_Coonstripe_Shrimp
- CA_Dungeness_Crab
- CA_Hagfish
- CA_Rock_Crab
- CA_Spiny_Lobster
- CA_Spot_Prawn
- MA_American_Lobster
- ME_American_Lobster
- OR_Dungeness_Crab
- RI_American_Lobster
- WA_Dungeness_Crab
- FF_American_Lobster
- FF_Sablefish
- FF_SE_Black_Sea_Bass
- CAN_American_Lobster
- CAN_Snow_Crab
- AUS_Southern_Rock_Lobster
- IDN_Lobster
Manufacturer codes
- ASH
- Ashored Innovations
- DES
- Desert Star Systems
- DEV
- DevOcean Solutions
- EDG
- EdgeTech
- FIO
- Fio Marine
- GUA
- Guardian Ropeless
- LIF
- Lift Labs
- NOV
- Nova Robotics
- PUG
- Puget Buoy
- ROP
- Ropeless Systems
- SME
- Smelts
- SUB
- Sub Sea Sonics
Example request
Replace the credential placeholder with your test key in your server-side client. All gear values are synthetic. This example has no timed release and no device whose serial number is used for fishing; use fresh test identifiers and accurate values for real submissions.
{
"api_key": "YOUR_TEST_API_KEY",
"format_version": 0.3,
"sets": [
{
"vessel_id": "ef3d9aa2-7e60-42f6-8bb0-b7ae1e57c001",
"set_id": "58b28f35-9d3b-4cb1-8caf-a2cfbb7d1002",
"deployment_type": "single",
"traps_in_set": 1,
"fishery": "MA_American_Lobster",
"permit_number": "TEST-ONLY-001",
"fisher_name": "Example Fisher",
"vessel_name": "Example Vessel",
"share_with": [],
"trawl_path": null,
"traps": [
{
"trap_id": "8483f040-d633-4338-80ab-e9098268c003",
"sequence": 1,
"latitude": 41.2980618,
"longitude": -70.9859833,
"deploy_datetime_utc": "2026-10-17T12:00:00Z",
"surface_datetime_utc": null,
"retrieved_datetime_utc": null,
"status": "deployed",
"accuracy": "GPS",
"release_type": "none",
"is_on_end": true,
"manufacturer": null,
"model": null,
"serial_number": null
}
]
}
]
}For timed gear, supply surface_datetime_utc. When a device’s serial number is
used for fishing, supply manufacturer, model and serial_number. Otherwise follow the null rules above.
To report retrieval, update the same set with all required fields, status: "retrieved" and the actual retrieved_datetime_utc. A subsequent deployment needs a new set_id; a reused trap_id may have only one deployed instance at a time.
Response
HTTP 200 · DeploymentsUploadResponse
The published response model describes possible fields. Your category, record sharing and field approvals determine the data you may receive.
| Field / type | Requirement | Description |
|---|---|---|
result UploadResult | null | Optional | View UploadResult fields |
UploadResult
| Field / type | Requirement | Description |
|---|---|---|
description string | Optional | Default: "Update confirmation" |
acknowledged boolean | Required | true if data successfully saved |
datetime_utc string (date-time) | Required | UTC timestamp when saved. ISO 8601 format. |
trap_count integer | Required | Number of traps in this upload. |
failed_sets array<FailedSet> | Required | List of sets that failed to upload. View FailedSet fields |
saved_sets array<SavedSet> | Required | List of sets that were saved. View SavedSet fields |
FailedSet
| Field / type | Requirement | Description |
|---|---|---|
set_id string | Required | UUID of set that failed to upload. |
reason string | Required | Reason for failure. |
SavedSet
| Field / type | Requirement | Description |
|---|---|---|
set_id string | Required | UUID of set that was saved. |
Errors and updates
HTTP 422 returns validation errors in detail, including loc (field
location), msg (message) and type. Handle other HTTP errors and
connection failures as well.
Inspect saved_sets and failed_sets; HTTP 200 alone does not confirm
every set was saved. Submit updates promptly when status, position or conditions change.
When notified of inaccurate location, status or identity data, acknowledge within one business day and correct within two. For other issues, acknowledge within two and correct within five, unless Polaris agrees a longer period under Policy §4.4.
HTTPValidationError
| Field / type | Requirement | Description |
|---|---|---|
detail array<ValidationError> | Optional | View ValidationError fields |
ValidationError
| Field / type | Requirement | Description |
|---|---|---|
loc array<string | integer> | Required | |
msg string | Required | |
type string | Required | |
input any | Optional | |
ctx object | Optional |