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

# Samples

## Search and list samples

> Public paginated listing of published samples with server-side filters derived from query parameters. Supports \`ordering\` using declared ordering field names.

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]},{}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PaginatedSampleListList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SampleList"}}}},"SampleList":{"type":"object","description":"Map model VariablePrecisionDecimalField columns to serializers that do not\nquantize values to a fixed decimal scale.","properties":{"sample_id":{"type":"integer","readOnly":true},"igsn":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"external_sample_id":{"type":"string","readOnly":true,"nullable":true},"sesar_code":{"type":"string","readOnly":true},"parent_sample":{"type":"string"},"object_type":{"type":"string","readOnly":true},"publish_date":{"type":"string","format":"date-time","readOnly":true},"last_update_date":{"type":"string","format":"date-time","readOnly":true},"size":{"type":"string","readOnly":true,"nullable":true},"general_material_type":{"type":"string","readOnly":true},"sample_material":{"type":"array","items":{"type":"string"},"readOnly":true},"field_name":{"type":"string","readOnly":true},"sample_description":{"type":"string","readOnly":true,"nullable":true},"purpose":{"type":"string","readOnly":true,"nullable":true},"geologic_age_verbatim":{"type":"string","readOnly":true,"nullable":true},"numeric_age_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"numeric_age_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"numeric_age_unit":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/NumericAgeUnitEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"age_description":{"type":"string","readOnly":true,"nullable":true},"geologic_age_younger":{"type":"string","readOnly":true},"geologic_age_older":{"type":"string","readOnly":true},"geologic_unit":{"type":"string","readOnly":true,"nullable":true},"latitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"longitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"latitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"longitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"northing":{"type":"string","readOnly":true},"easting":{"type":"string","readOnly":true},"zone":{"type":"string","readOnly":true},"depth_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"depth_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"depth_scale":{"type":"string","readOnly":true,"nullable":true},"vertical_datum":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/VerticalDatumEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"elevation":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"elevation_unit":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/ElevationUnitEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"location_method":{"type":"string","readOnly":true},"primary_location_type":{"type":"string","readOnly":true,"nullable":true},"primary_location_name":{"type":"string","readOnly":true,"nullable":true},"location_description":{"type":"string","readOnly":true,"nullable":true},"locality":{"type":"string","readOnly":true,"nullable":true},"locality_description":{"type":"string","readOnly":true,"nullable":true},"country":{"type":"string"},"province":{"type":"string","readOnly":true,"nullable":true},"county":{"type":"string","readOnly":true,"nullable":true},"city":{"type":"string","readOnly":true,"nullable":true},"sampling_method":{"type":"string","readOnly":true},"sampling_method_detail":{"type":"string","readOnly":true,"nullable":true},"cruise_field_prgrm":{"type":"string","readOnly":true},"collectors":{"type":"string","readOnly":true},"platform":{"type":"string","nullable":true,"readOnly":true},"launch_platform":{"type":"string","nullable":true,"readOnly":true},"launch_label":{"type":"string","readOnly":true,"nullable":true},"sampling_start_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"sampling_end_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"sampling_date_precision":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/SamplingDatePrecisionEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"other_names":{"type":"string","readOnly":true},"registration_date":{"type":"string","format":"date-time","readOnly":true},"current_archive":{"type":"string","readOnly":true},"original_archive":{"type":"string","readOnly":true},"current_archive_contact":{"type":"string","readOnly":true,"nullable":true},"original_archive_contact":{"type":"string","readOnly":true,"nullable":true},"is_linked":{"type":"boolean","readOnly":true,"default":false},"is_draft":{"type":"string","readOnly":true},"is_pending_review":{"type":"string","readOnly":true}},"required":["age_description","city","collectors","country","county","cruise_field_prgrm","current_archive","current_archive_contact","depth_max","depth_min","depth_scale","easting","elevation","elevation_unit","external_sample_id","field_name","general_material_type","geologic_age_older","geologic_age_verbatim","geologic_age_younger","geologic_unit","igsn","is_draft","is_linked","is_pending_review","last_update_date","latitude","latitude_end","launch_label","launch_platform","locality","locality_description","location_description","location_method","longitude","longitude_end","name","northing","numeric_age_max","numeric_age_min","numeric_age_unit","object_type","original_archive","original_archive_contact","other_names","parent_sample","platform","primary_location_name","primary_location_type","province","publish_date","purpose","registration_date","sample_description","sample_id","sample_material","sampling_date_precision","sampling_end_date","sampling_method","sampling_method_detail","sampling_start_date","sesar_code","size","vertical_datum","zone"]},"NumericAgeUnitEnum":{"enum":["years (yr)","thousand years (Ka)","million years (Ma)","billion years (Ga)","Before Present, 1950 (BP)","Anno Domini (AD)","Common Era (CE)","Before Common Era (BCE)"],"type":"string","description":"* `years (yr)` - years (yr)\n* `thousand years (Ka)` - thousand years (Ka)\n* `million years (Ma)` - million years (Ma)\n* `billion years (Ga)` - billion years (Ga)\n* `Before Present, 1950 (BP)` - Before Present, 1950 (BP)\n* `Anno Domini (AD)` - Anno Domini (AD)\n* `Common Era (CE)` - Common Era (CE)\n* `Before Common Era (BCE)` - Before Common Era (BCE)"},"NullEnum":{"enum":[null]},"VerticalDatumEnum":{"enum":["NAVD88","MSL"],"type":"string","description":"* `NAVD88` - NAVD88\n* `MSL` - Mean Sea Level (MSL)"},"ElevationUnitEnum":{"enum":["meters","kilometers","feet","miles"],"type":"string","description":"* `meters` - Meters\n* `kilometers` - Kilometers\n* `feet` - Feet\n* `miles` - Miles"},"SamplingDatePrecisionEnum":{"enum":["year","month","day","hour","minute","time"],"type":"string","description":"* `year` - Year\n* `month` - Month\n* `day` - Day\n* `hour` - Hour\n* `minute` - Minute\n* `time` - Time"}}},"paths":{"/api/samples/":{"get":{"operationId":"samples_list","description":"Public paginated listing of published samples with server-side filters derived from query parameters. Supports `ordering` using declared ordering field names.","summary":"Search and list samples","parameters":[{"in":"query","name":"age_max","schema":{"type":"number","format":"float"},"description":"Upper bound on numeric age (`numeric_age_max` ≤ value)."},{"in":"query","name":"age_min","schema":{"type":"number","format":"float"},"description":"Lower bound on numeric age (`numeric_age_min` ≥ value)."},{"in":"query","name":"batch_history_id","schema":{"type":"integer"},"description":"Restrict to samples registered in this batch history PK (requires view permission on the batch)."},{"in":"query","name":"bbox","schema":{"type":"string"},"description":"WGS84 bounding box as `min_lon,min_lat,max_lon,max_lat`."},{"in":"query","name":"check_related_resource_id","schema":{"type":"integer"},"description":"Annotates rows linked to this related-resource primary key (used with list UI)."},{"in":"query","name":"collected_after","schema":{"type":"string","format":"date-time"},"description":"Samples with `sampling_start_date` on or after this instant."},{"in":"query","name":"collected_before","schema":{"type":"string","format":"date-time"},"description":"Samples with `sampling_end_date` on or before this instant."},{"in":"query","name":"collector","schema":{"type":"string"},"description":"Substring match on individual or institution collector label."},{"in":"query","name":"continent","schema":{"type":"string"},"description":"Continent code or label (exact field match on `continent`)."},{"in":"query","name":"country","schema":{"type":"string"},"description":"Country ISO 3166 code(s), comma-separated (e.g. `US,CA`)."},{"in":"query","name":"current_archive","schema":{"type":"string"},"description":"Substring match on current archive label or alt label."},{"in":"query","name":"depth_max","schema":{"type":"number","format":"float"},"description":"Samples with `depth_max` ≤ this value."},{"in":"query","name":"depth_min","schema":{"type":"number","format":"float"},"description":"Samples with `depth_min` ≥ this value."},{"in":"query","name":"description","schema":{"type":"string"},"description":"Case-insensitive substring match on `sample_description`."},{"in":"query","name":"elevation_max","schema":{"type":"number","format":"float"},"description":"Samples with `elevation` ≤ this value (meters)."},{"in":"query","name":"elevation_min","schema":{"type":"number","format":"float"},"description":"Samples with `elevation` ≥ this value (meters)."},{"in":"query","name":"exclude_child_samples","schema":{"type":"string","enum":["false","true"]},"description":"If `true`, only top-level samples (`parent_sample` empty)."},{"in":"query","name":"external_sample_id","schema":{"type":"string"},"description":"Exact match on `external_sample_id`."},{"in":"query","name":"field_name","schema":{"type":"string"},"description":"Case-insensitive match on material name verbatim (`material_name_verbatim`)."},{"in":"query","name":"format","schema":{"type":"string"},"description":"Reserved pass-through (same allowlist as list views)."},{"in":"query","name":"geographic_region","schema":{"type":"string"},"description":"Substring match across locality, province, location fields, etc."},{"in":"query","name":"geologic_age_unit","schema":{"type":"string"},"description":"Substring match on `geologic_age_verbatim` or `geologic_unit`."},{"in":"query","name":"has_age","schema":{"type":"string","enum":["false","true"]},"description":"If `true`, only samples with non-null `numeric_age_min`, `numeric_age_max`, or `geologic_age_verbatim`."},{"in":"query","name":"has_geolocation","schema":{"type":"string","enum":["false","true"]},"description":"If `true`, only samples with a non-null `geom_latlong`."},{"in":"query","name":"has_images","schema":{"type":"string","enum":["false","true"]},"description":"If `true`, only samples with a related resource of type Image."},{"in":"query","name":"has_linked_resources","schema":{"type":"string","enum":["false","true"]},"description":"If `true`, samples with linked resources excluding Image."},{"in":"query","name":"has_resource_type","schema":{"type":"string"},"description":"Exact case-insensitive related-resource type label (e.g. publication type labels)."},{"in":"query","name":"igsn","schema":{"type":"string"},"description":"Case-insensitive substring match on IGSN."},{"in":"query","name":"initiative","schema":{"type":"string"},"description":"Substring match on initiative label or normalized label linked as cruise/program."},{"in":"query","name":"initiative_id","schema":{"type":"integer"},"description":"Restrict to samples linked to this initiative PK (requires view permission on initiative)."},{"in":"query","name":"is_draft","schema":{"type":"string","enum":["false","true"]},"description":"If `true`, only drafts (authenticated, owner contexts). If `false`, exclude drafts."},{"in":"query","name":"launch_platform","schema":{"type":"string"},"description":"Substring match on launch platform label or normalized label."},{"in":"query","name":"launch_platform_id","schema":{"type":"integer"},"description":"Restrict to samples using this launch platform PK (requires view permission)."},{"in":"query","name":"material","schema":{"type":"string"},"description":"Comma-separated material type IDs; expands to descendants for FK and M2M material match."},{"in":"query","name":"name","schema":{"type":"string"},"description":"Case-insensitive substring match on sample name."},{"in":"query","name":"object_type","schema":{"type":"string"},"description":"Object type label(s); matches `object_type__in`."},{"in":"query","name":"ordering","schema":{"type":"string"},"description":"Sort field(s). Prefix `-` for descending (same as DRF `OrderingFilter`)."},{"in":"query","name":"page","schema":{"type":"integer"},"description":"Page number when using paginated list endpoints."},{"in":"query","name":"page_size","schema":{"type":"integer"},"description":"Page size when using paginated list endpoints."},{"in":"query","name":"platform","schema":{"type":"string"},"description":"Substring match on platform label or normalized label."},{"in":"query","name":"platform_id","schema":{"type":"integer"},"description":"Restrict to samples using this platform PK (requires view permission)."},{"in":"query","name":"point","schema":{"type":"string"},"description":"WKT POINT (`POINT(lon lat)`); use with optional `radius` (meters, default 1000)."},{"in":"query","name":"polygon","schema":{"type":"string"},"description":"WKT or GeoJSON geometry; samples with `geom_latlong` inside the polygon (SRID 4326 if omitted)."},{"in":"query","name":"published_after","schema":{"type":"string","format":"date-time"},"description":"Samples with `publish_date` ≥ this instant."},{"in":"query","name":"published_before","schema":{"type":"string","format":"date-time"},"description":"Samples with `publish_date` ≤ this instant."},{"in":"query","name":"q","schema":{"type":"string"},"description":"Search substring matched against IGSN or name."},{"in":"query","name":"radius","schema":{"type":"number","format":"float"},"description":"Radius in meters around `point` (ignored without `point`)."},{"in":"query","name":"registered_after","schema":{"type":"string","format":"date-time"},"description":"Samples with `registration_date` ≥ this instant."},{"in":"query","name":"registered_before","schema":{"type":"string","format":"date-time"},"description":"Samples with `registration_date` ≤ this instant."},{"in":"query","name":"related_resource_id","schema":{"type":"integer"},"description":"Samples linked to this related resource PK (requires view permission)."},{"in":"query","name":"sample_group_id","schema":{"type":"integer"},"description":"Samples in this sample group PK (requires view permission on the group)."},{"in":"query","name":"sampling_method","schema":{"type":"string"},"description":"Case-insensitive match on linked sampling method label."},{"in":"query","name":"scope","schema":{"type":"string"},"description":"Visibility: `public` (published metadata), `personal` (your samples), `shared` (SESAR code grants), `personal_and_shared`; other values fall back to authenticated/public rules per server logic."},{"in":"query","name":"sesar_code","schema":{"type":"string"},"description":"SESAR code(s); matches `sesar_code__in`."},{"in":"query","name":"team_name","schema":{"type":"string"},"description":"Restrict to samples owned by this team (must be authenticated member)."}],"tags":["Samples"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSampleListList"}}},"description":""}}}}}}
```

## Register a new sample

> Authenticated registration. Provide \`sesar\_code\` (SESAR allocation) or \`team\` (custom DOI prefix path) together with required metadata. Nested objects such as \`platform\`, \`launch\_platform\`, and \`collectors\` are the primary input style; parallel \`\*\_id\` shortcuts exist for trusted clients and are omitted from this schema.

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleCreate":{"type":"object","description":"Sample registration payload. Prefer nested label-based objects (e.g. platform, launch_platform, collectors with individual/institution) over optional internal primary-key shortcuts, which remain accepted by the API.","properties":{"igsn":{"type":"string","maxLength":60},"name":{"type":"string","maxLength":255},"external_sample_id":{"type":"string","nullable":true,"maxLength":100},"sesar_code":{"type":"string","nullable":true},"team":{"type":"string","writeOnly":true,"nullable":true,"description":"Team name for custom DOI prefix registration (no sesar_code needed)."},"object_type":{"type":"string"},"general_material_type":{"type":"string","nullable":true},"field_name":{"type":"string","nullable":true,"maxLength":255},"sample_description":{"type":"string","nullable":true},"size":{"type":"string","nullable":true,"maxLength":255},"size_unit":{"type":"string","nullable":true,"maxLength":255},"purpose":{"type":"string","nullable":true,"maxLength":500},"parent_sample":{"type":"string","nullable":true},"external_parent_name":{"type":"string","nullable":true,"maxLength":1000},"external_parent_object_type":{"type":"string","nullable":true},"geologic_age_verbatim":{"type":"string","nullable":true,"maxLength":500},"numeric_age_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"numeric_age_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"numeric_age_unit":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/NumericAgeUnitEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"age_description":{"type":"string","nullable":true,"maxLength":1000},"geologic_unit":{"type":"string","nullable":true,"maxLength":500},"latitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"longitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"latitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"longitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"northing":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","writeOnly":true,"nullable":true},"easting":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","writeOnly":true,"nullable":true},"zone":{"type":"string","writeOnly":true,"nullable":true,"maxLength":32},"depth_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"depth_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"depth_scale":{"type":"string","nullable":true,"maxLength":255},"vertical_datum":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/VerticalDatumEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"elevation":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"elevation_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"elevation_unit":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/ElevationUnitEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"location_method":{"type":"string","nullable":true},"primary_location_type":{"type":"string","nullable":true,"maxLength":255},"primary_location_name":{"type":"string","nullable":true,"maxLength":1000},"location_description":{"type":"string","nullable":true,"maxLength":2000},"locality":{"type":"string","nullable":true,"maxLength":255},"locality_description":{"type":"string","nullable":true,"maxLength":2000},"country":{"type":"string","nullable":true},"province":{"type":"string","nullable":true,"maxLength":255},"county":{"type":"string","nullable":true,"maxLength":255},"city":{"type":"string","nullable":true,"maxLength":255},"sampling_method":{"type":"string","nullable":true,"description":"Sampling method label. Matched case-insensitively against existing vocabulary."},"sampling_method_detail":{"type":"string","nullable":true,"maxLength":1000},"cruise_field_prgrm":{"type":"string","nullable":true,"description":"Initiative label. Matched against owner's existing initiatives, created if new."},"platform":{"allOf":[{"$ref":"#/components/schemas/PlatformInput"}],"writeOnly":true,"nullable":true},"launch_platform":{"allOf":[{"$ref":"#/components/schemas/LaunchPlatformInput"}],"writeOnly":true,"nullable":true},"launch_label":{"type":"string","nullable":true,"maxLength":100},"sampling_start_date":{"type":"string","format":"date-time","nullable":true},"sampling_end_date":{"type":"string","format":"date-time","nullable":true},"sampling_date_precision":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/SamplingDatePrecisionEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"publish_date":{"type":"string","format":"date-time"},"registration_date":{"type":"string","format":"date-time","readOnly":true},"availability":{"type":"boolean","nullable":true},"storage_location":{"type":"string","nullable":true,"maxLength":255},"personal_collection_storage_location":{"type":"string","writeOnly":true,"nullable":true,"description":"Personal collection / storage location (alias for storage_location).","maxLength":255},"is_draft":{"type":"boolean","writeOnly":true,"description":"Set true to save as draft. Internal status is derived automatically."},"batch_history":{"type":"integer","writeOnly":true,"nullable":true,"description":"Optional batch history to add the created sample to (e.g. mint child from a batch detail page)."},"other_names":{"type":"array","items":{"type":"string","maxLength":255},"writeOnly":true},"material_types":{"type":"array","items":{"type":"string","maxLength":50},"writeOnly":true,"description":"List of material type labels"},"collectors":{"type":"array","items":{"$ref":"#/components/schemas/CollectorInput"},"writeOnly":true},"current_archive":{"allOf":[{"$ref":"#/components/schemas/ArchiveInput"}],"writeOnly":true,"nullable":true},"original_archive":{"allOf":[{"$ref":"#/components/schemas/ArchiveInput"}],"writeOnly":true,"nullable":true},"current_archive_id":{"type":"integer","writeOnly":true,"nullable":true},"original_archive_id":{"type":"integer","writeOnly":true,"nullable":true},"current_archive_contact":{"type":"string","nullable":true,"maxLength":1000},"original_archive_contact":{"type":"string","nullable":true,"maxLength":1000},"related_resources":{"type":"array","items":{"type":"integer","writeOnly":true},"writeOnly":true,"description":"IDs of publications, datasets, and other related resources to link. On update, replaces non-Image links; Image links are preserved. Omit on update to leave links unchanged."}},"required":["name","object_type","registration_date"]},"NumericAgeUnitEnum":{"enum":["years (yr)","thousand years (Ka)","million years (Ma)","billion years (Ga)","Before Present, 1950 (BP)","Anno Domini (AD)","Common Era (CE)","Before Common Era (BCE)"],"type":"string","description":"* `years (yr)` - years (yr)\n* `thousand years (Ka)` - thousand years (Ka)\n* `million years (Ma)` - million years (Ma)\n* `billion years (Ga)` - billion years (Ga)\n* `Before Present, 1950 (BP)` - Before Present, 1950 (BP)\n* `Anno Domini (AD)` - Anno Domini (AD)\n* `Common Era (CE)` - Common Era (CE)\n* `Before Common Era (BCE)` - Before Common Era (BCE)"},"BlankEnum":{"enum":[""]},"NullEnum":{"enum":[null]},"VerticalDatumEnum":{"enum":["NAVD88","MSL"],"type":"string","description":"* `NAVD88` - NAVD88\n* `MSL` - Mean Sea Level (MSL)"},"ElevationUnitEnum":{"enum":["meters","kilometers","feet","miles"],"type":"string","description":"* `meters` - Meters\n* `kilometers` - Kilometers\n* `feet` - Feet\n* `miles` - Miles"},"PlatformInput":{"type":"object","description":"Nested input for platform: label + type.","properties":{"label":{"type":"string","nullable":true,"maxLength":100},"platform_type":{"type":"string","nullable":true,"maxLength":50},"description":{"type":"string","nullable":true}}},"LaunchPlatformInput":{"type":"object","description":"Nested input for launch platform: label + type.","properties":{"label":{"type":"string","nullable":true,"maxLength":100},"launch_type":{"type":"string","nullable":true,"maxLength":50}}},"SamplingDatePrecisionEnum":{"enum":["year","month","day","hour","minute","time"],"type":"string","description":"* `year` - Year\n* `month` - Month\n* `day` - Day\n* `hour` - Hour\n* `minute` - Minute\n* `time` - Time"},"CollectorInput":{"type":"object","description":"Collector reference (id or inline individual/institution payload).","properties":{"description":{"type":"string","nullable":true},"individual":{"allOf":[{"$ref":"#/components/schemas/CollectorIndividualInput"}],"nullable":true},"institution":{"allOf":[{"$ref":"#/components/schemas/CollectorInstitutionInput"}],"nullable":true}}},"CollectorIndividualInput":{"type":"object","description":"Inline individual payload for collector resolution/create.","properties":{"label":{"type":"string","nullable":true,"maxLength":200},"fname":{"type":"string","nullable":true,"maxLength":100},"lname":{"type":"string","nullable":true,"maxLength":100},"individual_uri":{"type":"string","nullable":true,"maxLength":255}}},"CollectorInstitutionInput":{"type":"object","description":"Inline institution payload for collector resolution/create.","properties":{"label":{"type":"string","nullable":true,"maxLength":200},"ror":{"type":"string","nullable":true,"maxLength":25},"city":{"type":"string","nullable":true,"maxLength":255},"country":{"type":"string","nullable":true}}},"ArchiveInput":{"type":"object","description":"Inline archive payload for create-or-match by label.","properties":{"label":{"type":"string","maxLength":200},"alt_label":{"type":"string","nullable":true,"maxLength":200},"city":{"type":"string","nullable":true,"maxLength":255},"country":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"url":{"type":"string","nullable":true,"maxLength":200},"uri":{"type":"string","nullable":true,"maxLength":25}},"required":["label"]}}},"paths":{"/api/samples/":{"post":{"operationId":"samples_create","description":"Authenticated registration. Provide `sesar_code` (SESAR allocation) or `team` (custom DOI prefix path) together with required metadata. Nested objects such as `platform`, `launch_platform`, and `collectors` are the primary input style; parallel `*_id` shortcuts exist for trusted clients and are omitted from this schema.","summary":"Register a new sample","tags":["Samples"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleCreate"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/SampleCreate"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SampleCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleCreate"}}},"description":""}}}}}}
```

## Retrieve sample for viewing or editing

> Returns registration-aligned sample metadata. Published samples are readable without authentication; restricted samples require authentication and view permission.

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]},{}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleDetail":{"type":"object","description":"Read-only sample metadata aligned with registration/create payload shape\n(labels for vocabulary FKs, IDs where the create API accepts *_id fields).","properties":{"igsn":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"sesar_code":{"type":"string","readOnly":true},"team_id":{"type":"integer","readOnly":true,"nullable":true},"owner_display":{"type":"string","readOnly":true},"object_type":{"type":"string","readOnly":true},"general_material_type":{"type":"string","readOnly":true},"field_name":{"type":"string","readOnly":true},"sample_description":{"type":"string","readOnly":true,"nullable":true},"size":{"type":"string","readOnly":true,"nullable":true},"size_unit":{"type":"string","readOnly":true,"nullable":true},"purpose":{"type":"string","readOnly":true,"nullable":true},"parent_sample":{"type":"string","readOnly":true},"external_parent_name":{"type":"string","readOnly":true,"nullable":true},"external_parent_object_type":{"type":"string","readOnly":true},"geologic_age_verbatim":{"type":"string","readOnly":true,"nullable":true},"numeric_age_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"numeric_age_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"numeric_age_unit":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/NumericAgeUnitEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"age_description":{"type":"string","readOnly":true,"nullable":true},"geologic_unit":{"type":"string","readOnly":true,"nullable":true},"latitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"longitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"latitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"longitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"northing":{"type":"string","readOnly":true},"easting":{"type":"string","readOnly":true},"zone":{"type":"string","readOnly":true},"depth_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"depth_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"depth_scale":{"type":"string","readOnly":true,"nullable":true},"vertical_datum":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/VerticalDatumEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"elevation":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"elevation_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","readOnly":true,"nullable":true},"elevation_unit":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/ElevationUnitEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"location_method":{"type":"string","readOnly":true},"primary_location_type":{"type":"string","readOnly":true,"nullable":true},"primary_location_name":{"type":"string","readOnly":true,"nullable":true},"location_description":{"type":"string","readOnly":true,"nullable":true},"locality":{"type":"string","readOnly":true,"nullable":true},"locality_description":{"type":"string","readOnly":true,"nullable":true},"country":{"type":"string","readOnly":true},"province":{"type":"string","readOnly":true,"nullable":true},"county":{"type":"string","readOnly":true,"nullable":true},"city":{"type":"string","readOnly":true,"nullable":true},"sampling_method":{"type":"string","readOnly":true},"sampling_method_detail":{"type":"string","readOnly":true,"nullable":true},"cruise_field_prgrm":{"type":"string","readOnly":true},"cruise_field_prgrm_id":{"type":"integer","readOnly":true,"nullable":true},"platform":{"allOf":[{"$ref":"#/components/schemas/Platform"}],"readOnly":true},"platform_id":{"type":"integer","readOnly":true,"nullable":true},"launch_platform":{"allOf":[{"$ref":"#/components/schemas/LaunchPlatform"}],"readOnly":true},"launch_platform_id":{"type":"integer","readOnly":true,"nullable":true},"launch_label":{"type":"string","readOnly":true,"nullable":true},"sampling_start_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"sampling_end_date":{"type":"string","format":"date-time","readOnly":true,"nullable":true},"sampling_date_precision":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/SamplingDatePrecisionEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"publish_date":{"type":"string","format":"date-time","readOnly":true},"registration_date":{"type":"string","format":"date-time","readOnly":true},"availability":{"type":"boolean","readOnly":true,"nullable":true},"storage_location":{"type":"string","readOnly":true,"nullable":true},"metadata_store_status":{"readOnly":true,"nullable":true,"oneOf":[{"$ref":"#/components/schemas/MetadataStoreStatusEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"is_draft":{"type":"string","readOnly":true},"is_pending_review":{"type":"string","readOnly":true},"batch_history_id":{"type":"string","readOnly":true},"other_names":{"type":"string","readOnly":true},"material_types":{"type":"string","readOnly":true},"collectors":{"type":"string","readOnly":true},"current_archive":{"allOf":[{"$ref":"#/components/schemas/Archive"}],"readOnly":true},"original_archive":{"allOf":[{"$ref":"#/components/schemas/Archive"}],"readOnly":true},"current_archive_contact":{"type":"string","readOnly":true,"nullable":true},"original_archive_contact":{"type":"string","readOnly":true,"nullable":true},"initiative":{"allOf":[{"$ref":"#/components/schemas/Initiative"}],"readOnly":true},"related_resources":{"type":"string","readOnly":true},"can_edit":{"type":"string","readOnly":true},"can_deactivate":{"type":"string","readOnly":true}},"required":["age_description","availability","batch_history_id","can_deactivate","can_edit","city","collectors","country","county","cruise_field_prgrm","cruise_field_prgrm_id","current_archive","current_archive_contact","depth_max","depth_min","depth_scale","easting","elevation","elevation_end","elevation_unit","external_parent_name","external_parent_object_type","field_name","general_material_type","geologic_age_verbatim","geologic_unit","igsn","initiative","is_draft","is_pending_review","latitude","latitude_end","launch_label","launch_platform","launch_platform_id","locality","locality_description","location_description","location_method","longitude","longitude_end","material_types","metadata_store_status","name","northing","numeric_age_max","numeric_age_min","numeric_age_unit","object_type","original_archive","original_archive_contact","other_names","owner_display","parent_sample","platform","platform_id","primary_location_name","primary_location_type","province","publish_date","purpose","registration_date","related_resources","sample_description","sampling_date_precision","sampling_end_date","sampling_method","sampling_method_detail","sampling_start_date","sesar_code","size","size_unit","storage_location","team_id","vertical_datum","zone"]},"NumericAgeUnitEnum":{"enum":["years (yr)","thousand years (Ka)","million years (Ma)","billion years (Ga)","Before Present, 1950 (BP)","Anno Domini (AD)","Common Era (CE)","Before Common Era (BCE)"],"type":"string","description":"* `years (yr)` - years (yr)\n* `thousand years (Ka)` - thousand years (Ka)\n* `million years (Ma)` - million years (Ma)\n* `billion years (Ga)` - billion years (Ga)\n* `Before Present, 1950 (BP)` - Before Present, 1950 (BP)\n* `Anno Domini (AD)` - Anno Domini (AD)\n* `Common Era (CE)` - Common Era (CE)\n* `Before Common Era (BCE)` - Before Common Era (BCE)"},"NullEnum":{"enum":[null]},"VerticalDatumEnum":{"enum":["NAVD88","MSL"],"type":"string","description":"* `NAVD88` - NAVD88\n* `MSL` - Mean Sea Level (MSL)"},"ElevationUnitEnum":{"enum":["meters","kilometers","feet","miles"],"type":"string","description":"* `meters` - Meters\n* `kilometers` - Kilometers\n* `feet` - Feet\n* `miles` - Miles"},"Platform":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"label":{"type":"string","nullable":true,"maxLength":100},"norm_label":{"type":"string","nullable":true,"maxLength":100},"description":{"type":"string","nullable":true},"platform_type_name":{"type":"string","writeOnly":true,"nullable":true},"platform_type_id":{"type":"integer","nullable":true},"platform_type_description":{"type":"string","writeOnly":true,"nullable":true},"host_platform_id":{"type":"integer","maximum":2147483647,"minimum":-2147483648,"nullable":true},"operator":{"type":"string","readOnly":true},"operator_id":{"type":"integer","nullable":true},"date_commissioned":{"type":"string","format":"date","nullable":true},"user_owner":{"type":"integer","readOnly":true,"nullable":true},"team_owner":{"type":"integer","readOnly":true,"nullable":true}},"required":["id","operator","team_owner","user_owner"]},"LaunchPlatform":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"label":{"type":"string","nullable":true,"maxLength":100},"norm_label":{"type":"string","nullable":true,"maxLength":100},"description":{"type":"string","nullable":true},"host_platform_id":{"type":"integer","maximum":2147483647,"minimum":-2147483648,"nullable":true},"launch_type":{"type":"string","readOnly":true},"launch_type_id":{"type":"integer","nullable":true},"operator":{"type":"string","readOnly":true},"operator_id":{"type":"integer","nullable":true},"date_commissioned":{"type":"string","format":"date","nullable":true},"user_owner":{"type":"integer","readOnly":true,"nullable":true},"team_owner":{"type":"integer","readOnly":true,"nullable":true}},"required":["id","launch_type","operator","team_owner","user_owner"]},"SamplingDatePrecisionEnum":{"enum":["year","month","day","hour","minute","time"],"type":"string","description":"* `year` - Year\n* `month` - Month\n* `day` - Day\n* `hour` - Hour\n* `minute` - Minute\n* `time` - Time"},"MetadataStoreStatusEnum":{"enum":["deactivated-datacite","do-not-register","registered","registered-datacite","registered-datacite-v2","registered-datacite-v3","draft","pending-review","pending-batch-review"],"type":"string","description":"* `deactivated-datacite` - Deactivated (DataCite)\n* `do-not-register` - Do Not Register\n* `registered` - Registered\n* `registered-datacite` - Registered (DataCite)\n* `registered-datacite-v2` - Registered (DataCite v2)\n* `registered-datacite-v3` - Registered (DataCite v3)\n* `draft` - Draft\n* `pending-review` - Pending Review\n* `pending-batch-review` - Pending Batch Review"},"Archive":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"label":{"type":"string","maxLength":200},"alt_label":{"type":"string","nullable":true,"maxLength":200},"description":{"type":"string","nullable":true},"country":{"type":"string","readOnly":true},"country_subdivision":{"type":"string","nullable":true,"maxLength":255},"city":{"type":"string","nullable":true,"maxLength":255},"url":{"type":"string","nullable":true,"maxLength":200},"uri":{"type":"string","nullable":true,"maxLength":36},"parent_institution":{"allOf":[{"$ref":"#/components/schemas/Institution"}],"readOnly":true}},"required":["country","id","label","parent_institution"]},"Institution":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"institution_type":{"type":"string","readOnly":true},"label":{"type":"string","maxLength":200},"alt_label":{"type":"string","nullable":true,"maxLength":200},"description":{"type":"string","nullable":true},"country":{"type":"string","readOnly":true},"country_subdivision":{"type":"string","nullable":true,"maxLength":255},"city":{"type":"string","nullable":true,"maxLength":255},"ror":{"type":"string","nullable":true,"maxLength":25},"parent_institutions":{"type":"string","readOnly":true},"can_edit":{"type":"string","readOnly":true},"created_by":{"type":"integer","nullable":true}},"required":["can_edit","country","id","institution_type","label","parent_institutions"]},"Initiative":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"label":{"type":"string","maxLength":255},"description":{"type":"string","nullable":true},"funding":{"type":"string","nullable":true,"maxLength":50},"begin_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"initiative_uri":{"type":"string","nullable":true,"maxLength":255},"user_owner":{"type":"integer","nullable":true},"team_owner":{"type":"integer","nullable":true}},"required":["id","label"]}}},"paths":{"/api/samples/{igsn}/":{"get":{"operationId":"samples_retrieve","description":"Returns registration-aligned sample metadata. Published samples are readable without authentication; restricted samples require authentication and view permission.","summary":"Retrieve sample for viewing or editing","parameters":[{"in":"path","name":"igsn","schema":{"type":"string"},"required":true}],"tags":["Samples"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleDetail"}}},"description":""}}}}}}
```

## Partially update sample metadata

> Omitted fields are unchanged. When provided, \`other\_names\`, \`material\_types\`, and collector inputs replace prior collector agents. Archive fields set or clear the current\_archive / original\_archive foreign keys.

```json
{"openapi":"3.0.3","info":{"title":"SESAR API","version":"1.0.0"},"security":[{"tokenAuth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token-based authentication with required prefix \"Token\""},"jwtAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PatchedSampleUpdate":{"type":"object","description":"Sample registration payload. Prefer nested label-based objects (e.g. platform, launch_platform, collectors with individual/institution) over optional internal primary-key shortcuts, which remain accepted by the API.","properties":{"igsn":{"type":"string","readOnly":true},"name":{"type":"string","maxLength":255},"external_sample_id":{"type":"string","nullable":true,"maxLength":100},"sesar_code":{"type":"string","readOnly":true},"team":{"type":"string","readOnly":true},"object_type":{"type":"string"},"general_material_type":{"type":"string","nullable":true},"field_name":{"type":"string","nullable":true,"maxLength":255},"sample_description":{"type":"string","nullable":true},"size":{"type":"string","nullable":true,"maxLength":255},"size_unit":{"type":"string","nullable":true,"maxLength":255},"purpose":{"type":"string","nullable":true,"maxLength":500},"parent_sample":{"type":"string","nullable":true},"external_parent_name":{"type":"string","nullable":true,"maxLength":1000},"external_parent_object_type":{"type":"string","nullable":true},"geologic_age_verbatim":{"type":"string","nullable":true,"maxLength":500},"numeric_age_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"numeric_age_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"numeric_age_unit":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/NumericAgeUnitEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"age_description":{"type":"string","nullable":true,"maxLength":1000},"geologic_unit":{"type":"string","nullable":true,"maxLength":500},"latitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"longitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"latitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"longitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"northing":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","writeOnly":true,"nullable":true},"easting":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","writeOnly":true,"nullable":true},"zone":{"type":"string","writeOnly":true,"nullable":true,"maxLength":32},"depth_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"depth_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"depth_scale":{"type":"string","nullable":true,"maxLength":255},"vertical_datum":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/VerticalDatumEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"elevation":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"elevation_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"elevation_unit":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/ElevationUnitEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"location_method":{"type":"string","nullable":true},"primary_location_type":{"type":"string","nullable":true,"maxLength":255},"primary_location_name":{"type":"string","nullable":true,"maxLength":1000},"location_description":{"type":"string","nullable":true,"maxLength":2000},"locality":{"type":"string","nullable":true,"maxLength":255},"locality_description":{"type":"string","nullable":true,"maxLength":2000},"country":{"type":"string","nullable":true},"province":{"type":"string","nullable":true,"maxLength":255},"county":{"type":"string","nullable":true,"maxLength":255},"city":{"type":"string","nullable":true,"maxLength":255},"sampling_method":{"type":"string","nullable":true,"description":"Sampling method label. Matched case-insensitively against existing vocabulary."},"sampling_method_detail":{"type":"string","nullable":true,"maxLength":1000},"cruise_field_prgrm":{"type":"string","nullable":true,"description":"Initiative label. Matched against owner's existing initiatives, created if new."},"platform":{"allOf":[{"$ref":"#/components/schemas/PlatformInput"}],"writeOnly":true,"nullable":true},"launch_platform":{"allOf":[{"$ref":"#/components/schemas/LaunchPlatformInput"}],"writeOnly":true,"nullable":true},"launch_label":{"type":"string","nullable":true,"maxLength":100},"sampling_start_date":{"type":"string","format":"date-time","nullable":true},"sampling_end_date":{"type":"string","format":"date-time","nullable":true},"sampling_date_precision":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/SamplingDatePrecisionEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"publish_date":{"type":"string","format":"date-time"},"registration_date":{"type":"string","format":"date-time","readOnly":true},"availability":{"type":"boolean","nullable":true},"storage_location":{"type":"string","nullable":true,"maxLength":255},"personal_collection_storage_location":{"type":"string","writeOnly":true,"nullable":true,"description":"Personal collection / storage location (alias for storage_location).","maxLength":255},"is_draft":{"type":"boolean","writeOnly":true,"description":"Set true to save as draft. Internal status is derived automatically."},"batch_history":{"type":"integer","writeOnly":true,"nullable":true,"description":"Optional batch history to add the created sample to (e.g. mint child from a batch detail page)."},"other_names":{"type":"array","items":{"type":"string","maxLength":255},"writeOnly":true},"material_types":{"type":"array","items":{"type":"string","maxLength":50},"writeOnly":true,"description":"List of material type labels"},"collectors":{"type":"array","items":{"$ref":"#/components/schemas/CollectorInput"},"writeOnly":true},"current_archive":{"allOf":[{"$ref":"#/components/schemas/ArchiveInput"}],"writeOnly":true,"nullable":true},"original_archive":{"allOf":[{"$ref":"#/components/schemas/ArchiveInput"}],"writeOnly":true,"nullable":true},"current_archive_id":{"type":"integer","writeOnly":true,"nullable":true},"original_archive_id":{"type":"integer","writeOnly":true,"nullable":true},"current_archive_contact":{"type":"string","nullable":true,"maxLength":1000},"original_archive_contact":{"type":"string","nullable":true,"maxLength":1000},"related_resources":{"type":"array","items":{"type":"integer","writeOnly":true},"writeOnly":true,"description":"IDs of publications, datasets, and other related resources to link. On update, replaces non-Image links; Image links are preserved. Omit on update to leave links unchanged."}}},"NumericAgeUnitEnum":{"enum":["years (yr)","thousand years (Ka)","million years (Ma)","billion years (Ga)","Before Present, 1950 (BP)","Anno Domini (AD)","Common Era (CE)","Before Common Era (BCE)"],"type":"string","description":"* `years (yr)` - years (yr)\n* `thousand years (Ka)` - thousand years (Ka)\n* `million years (Ma)` - million years (Ma)\n* `billion years (Ga)` - billion years (Ga)\n* `Before Present, 1950 (BP)` - Before Present, 1950 (BP)\n* `Anno Domini (AD)` - Anno Domini (AD)\n* `Common Era (CE)` - Common Era (CE)\n* `Before Common Era (BCE)` - Before Common Era (BCE)"},"BlankEnum":{"enum":[""]},"NullEnum":{"enum":[null]},"VerticalDatumEnum":{"enum":["NAVD88","MSL"],"type":"string","description":"* `NAVD88` - NAVD88\n* `MSL` - Mean Sea Level (MSL)"},"ElevationUnitEnum":{"enum":["meters","kilometers","feet","miles"],"type":"string","description":"* `meters` - Meters\n* `kilometers` - Kilometers\n* `feet` - Feet\n* `miles` - Miles"},"PlatformInput":{"type":"object","description":"Nested input for platform: label + type.","properties":{"label":{"type":"string","nullable":true,"maxLength":100},"platform_type":{"type":"string","nullable":true,"maxLength":50},"description":{"type":"string","nullable":true}}},"LaunchPlatformInput":{"type":"object","description":"Nested input for launch platform: label + type.","properties":{"label":{"type":"string","nullable":true,"maxLength":100},"launch_type":{"type":"string","nullable":true,"maxLength":50}}},"SamplingDatePrecisionEnum":{"enum":["year","month","day","hour","minute","time"],"type":"string","description":"* `year` - Year\n* `month` - Month\n* `day` - Day\n* `hour` - Hour\n* `minute` - Minute\n* `time` - Time"},"CollectorInput":{"type":"object","description":"Collector reference (id or inline individual/institution payload).","properties":{"description":{"type":"string","nullable":true},"individual":{"allOf":[{"$ref":"#/components/schemas/CollectorIndividualInput"}],"nullable":true},"institution":{"allOf":[{"$ref":"#/components/schemas/CollectorInstitutionInput"}],"nullable":true}}},"CollectorIndividualInput":{"type":"object","description":"Inline individual payload for collector resolution/create.","properties":{"label":{"type":"string","nullable":true,"maxLength":200},"fname":{"type":"string","nullable":true,"maxLength":100},"lname":{"type":"string","nullable":true,"maxLength":100},"individual_uri":{"type":"string","nullable":true,"maxLength":255}}},"CollectorInstitutionInput":{"type":"object","description":"Inline institution payload for collector resolution/create.","properties":{"label":{"type":"string","nullable":true,"maxLength":200},"ror":{"type":"string","nullable":true,"maxLength":25},"city":{"type":"string","nullable":true,"maxLength":255},"country":{"type":"string","nullable":true}}},"ArchiveInput":{"type":"object","description":"Inline archive payload for create-or-match by label.","properties":{"label":{"type":"string","maxLength":200},"alt_label":{"type":"string","nullable":true,"maxLength":200},"city":{"type":"string","nullable":true,"maxLength":255},"country":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"url":{"type":"string","nullable":true,"maxLength":200},"uri":{"type":"string","nullable":true,"maxLength":25}},"required":["label"]},"SampleUpdate":{"type":"object","description":"Sample registration payload. Prefer nested label-based objects (e.g. platform, launch_platform, collectors with individual/institution) over optional internal primary-key shortcuts, which remain accepted by the API.","properties":{"igsn":{"type":"string","readOnly":true},"name":{"type":"string","maxLength":255},"external_sample_id":{"type":"string","nullable":true,"maxLength":100},"sesar_code":{"type":"string","readOnly":true},"team":{"type":"string","readOnly":true},"object_type":{"type":"string"},"general_material_type":{"type":"string","nullable":true},"field_name":{"type":"string","nullable":true,"maxLength":255},"sample_description":{"type":"string","nullable":true},"size":{"type":"string","nullable":true,"maxLength":255},"size_unit":{"type":"string","nullable":true,"maxLength":255},"purpose":{"type":"string","nullable":true,"maxLength":500},"parent_sample":{"type":"string","nullable":true},"external_parent_name":{"type":"string","nullable":true,"maxLength":1000},"external_parent_object_type":{"type":"string","nullable":true},"geologic_age_verbatim":{"type":"string","nullable":true,"maxLength":500},"numeric_age_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"numeric_age_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"numeric_age_unit":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/NumericAgeUnitEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"age_description":{"type":"string","nullable":true,"maxLength":1000},"geologic_unit":{"type":"string","nullable":true,"maxLength":500},"latitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"longitude":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"latitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"longitude_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"northing":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","writeOnly":true,"nullable":true},"easting":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","writeOnly":true,"nullable":true},"zone":{"type":"string","writeOnly":true,"nullable":true,"maxLength":32},"depth_min":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"depth_max":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"depth_scale":{"type":"string","nullable":true,"maxLength":255},"vertical_datum":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/VerticalDatumEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"elevation":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"elevation_end":{"type":"string","format":"decimal","pattern":"^-?\\d{0,10}(?:\\.\\d{0,20})?$","nullable":true},"elevation_unit":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/ElevationUnitEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"location_method":{"type":"string","nullable":true},"primary_location_type":{"type":"string","nullable":true,"maxLength":255},"primary_location_name":{"type":"string","nullable":true,"maxLength":1000},"location_description":{"type":"string","nullable":true,"maxLength":2000},"locality":{"type":"string","nullable":true,"maxLength":255},"locality_description":{"type":"string","nullable":true,"maxLength":2000},"country":{"type":"string","nullable":true},"province":{"type":"string","nullable":true,"maxLength":255},"county":{"type":"string","nullable":true,"maxLength":255},"city":{"type":"string","nullable":true,"maxLength":255},"sampling_method":{"type":"string","nullable":true,"description":"Sampling method label. Matched case-insensitively against existing vocabulary."},"sampling_method_detail":{"type":"string","nullable":true,"maxLength":1000},"cruise_field_prgrm":{"type":"string","nullable":true,"description":"Initiative label. Matched against owner's existing initiatives, created if new."},"platform":{"allOf":[{"$ref":"#/components/schemas/PlatformInput"}],"writeOnly":true,"nullable":true},"launch_platform":{"allOf":[{"$ref":"#/components/schemas/LaunchPlatformInput"}],"writeOnly":true,"nullable":true},"launch_label":{"type":"string","nullable":true,"maxLength":100},"sampling_start_date":{"type":"string","format":"date-time","nullable":true},"sampling_end_date":{"type":"string","format":"date-time","nullable":true},"sampling_date_precision":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/SamplingDatePrecisionEnum"},{"$ref":"#/components/schemas/BlankEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"publish_date":{"type":"string","format":"date-time"},"registration_date":{"type":"string","format":"date-time","readOnly":true},"availability":{"type":"boolean","nullable":true},"storage_location":{"type":"string","nullable":true,"maxLength":255},"personal_collection_storage_location":{"type":"string","writeOnly":true,"nullable":true,"description":"Personal collection / storage location (alias for storage_location).","maxLength":255},"is_draft":{"type":"boolean","writeOnly":true,"description":"Set true to save as draft. Internal status is derived automatically."},"batch_history":{"type":"integer","writeOnly":true,"nullable":true,"description":"Optional batch history to add the created sample to (e.g. mint child from a batch detail page)."},"other_names":{"type":"array","items":{"type":"string","maxLength":255},"writeOnly":true},"material_types":{"type":"array","items":{"type":"string","maxLength":50},"writeOnly":true,"description":"List of material type labels"},"collectors":{"type":"array","items":{"$ref":"#/components/schemas/CollectorInput"},"writeOnly":true},"current_archive":{"allOf":[{"$ref":"#/components/schemas/ArchiveInput"}],"writeOnly":true,"nullable":true},"original_archive":{"allOf":[{"$ref":"#/components/schemas/ArchiveInput"}],"writeOnly":true,"nullable":true},"current_archive_id":{"type":"integer","writeOnly":true,"nullable":true},"original_archive_id":{"type":"integer","writeOnly":true,"nullable":true},"current_archive_contact":{"type":"string","nullable":true,"maxLength":1000},"original_archive_contact":{"type":"string","nullable":true,"maxLength":1000},"related_resources":{"type":"array","items":{"type":"integer","writeOnly":true},"writeOnly":true,"description":"IDs of publications, datasets, and other related resources to link. On update, replaces non-Image links; Image links are preserved. Omit on update to leave links unchanged."}},"required":["igsn","name","object_type","registration_date","sesar_code","team"]}}},"paths":{"/api/samples/{igsn}/":{"patch":{"operationId":"samples_partial_update","description":"Omitted fields are unchanged. When provided, `other_names`, `material_types`, and collector inputs replace prior collector agents. Archive fields set or clear the current_archive / original_archive foreign keys.","summary":"Partially update sample metadata","parameters":[{"in":"path","name":"igsn","schema":{"type":"string"},"required":true}],"tags":["Samples"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedSampleUpdate"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PatchedSampleUpdate"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PatchedSampleUpdate"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleUpdate"}}},"description":""}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.geosamples.org/api/samples.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.