### Wildbook API Bulk Import Task Creation Example

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Provides a cURL example for submitting data for bulk import into Wildbook. This endpoint requires a prior file upload and allows specifying options like validation-only mode, skipping detection, or identification. The example includes the request payload with sample data.

```bash
# Create a bulk import task
curl -X POST "https://your-wildbook-instance/api/v3/bulk-import" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "submissionId": "bulk-upload-uuid",
    "sourceName": "Pacific Survey 2024",
    "validateOnly": false,
    "skipDetection": false,
    "skipIdentification": false,
    "data": [
      {
        "genus": "Megaptera",
        "specificEpithet": "novaeangliae",
        "year": 2024,
        "month": 1,
        "day": 15,
        "locationId": "Hawaii",
        "assetFilenames": ["survey_001.jpg", "survey_002.jpg"]
      },
      {
        "genus": "Megaptera",
        "specificEpithet": "novaeangliae",
        "year": 2024,
        "month": 1,
        "day": 16,
        "locationId": "Maui",
        "assetFilenames": ["survey_003.jpg"]
      }
    ]
  }'
```

--------------------------------

### Install PostGIS SQL Scripts

Source: https://github.com/wildmeorg/wildbook/blob/main/archive/postgis/README.md

Commands to install PostGIS SQL scripts for water polygon data. Requires psql and a gzipped SQL file.

```sql
zcat simplified_water_polygons.sql.gz | psql
```

```sql
psql < water_functions.sql
```

--------------------------------

### Wildbook API Search Encounters Query Example

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Demonstrates how to perform advanced search queries against the encounter index using cURL. This example searches for encounters with specific criteria like genus, species, and year, with filtering by location. It includes the request payload and a sample successful response.

```bash
# Search for encounters with specific criteria
curl -X POST "https://your-wildbook-instance/api/v3/search/encounter?from=0&size=20&sort=year&sortOrder=desc" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "query": {
      "bool": {
        "must": [
          {"term": {"genus": "Megaptera"}},
          {"term": {"specificEpithet": "novaeangliae"}},
          {"range": {"year": {"gte": 2020}}}
        ],
        "filter": [
          {"term": {"locationId": "Hawaii"}}
        ]
      }
    }
  }'
```

```json
# Response (200 OK):
# Headers:
# X-Wildbook-Total-Hits: 156
# X-Wildbook-Search-Query-Id: search-query-uuid

{
  "success": true,
  "searchQueryId": "search-query-uuid",
  "hits": [
    {
      "id": "enc-uuid-1",
      "genus": "Megaptera",
      "specificEpithet": "novaeangliae",
      "year": 2024,
      "month": 1,
      "day": 15,
      "locationId": "Hawaii",
      "individualId": "indiv-uuid-1"
    },
    {
      "id": "enc-uuid-2",
      "genus": "Megaptera",
      "specificEpithet": "novaeangliae",
      "year": 2023,
      "month": 12,
      "day": 20,
      "locationId": "Hawaii"
    }
  ],
  "query": {
    "bool": {
      "must": [{"term": {"genus": "Megaptera"}}]
    }
  }
}
```

--------------------------------

### Wildbook API Search Individuals Query Example

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Shows how to query the individuals index for specific marked individuals using cURL. This example searches for individuals based on names or alternate IDs, combined with genus criteria. It includes the request payload and a sample successful response.

```bash
# Search for individuals by name or characteristics
curl -X POST "https://your-wildbook-instance/api/v3/search/individual?from=0&size=10" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "query": {
      "bool": {
        "should": [
          {"match": {"names": "Splash"}},
          {"match": {"alternateId": "HI-2019"}}
        ],
        "must": [
          {"term": {"genus": "Megaptera"}}
        ]
      }
    }
  }'
```

```json
# Response (200 OK):
{
  "success": true,
  "searchQueryId": "search-query-uuid-2",
  "hits": [
    {
      "id": "indiv-uuid-1",
      "names": {"Nickname": "Splash"},
      "genus": "Megaptera",
      "specificEpithet": "novaeangliae",
      "numberEncounters": 15,
      "sex": "female"
    }
  ]
}
```

--------------------------------

### Manage Wildbook Docker Containers

Source: https://github.com/wildmeorg/wildbook/blob/main/devops/README.md

Commands to start or restart the Wildbook development environment using docker-compose.

```bash
docker-compose up -d
docker-compose restart wildbook
```

--------------------------------

### Use React Testing Library Providers

Source: https://github.com/wildmeorg/wildbook/blob/main/src/test/README.md

Example of using the renderWithProviders utility to wrap React components with necessary context providers during testing.

```javascript
import { renderWithProviders } from '../../../utils/utils';

renderWithProviders(<MyComponent />);
```

--------------------------------

### Wildbook API Re-execute Stored Search Query Example

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Demonstrates how to re-execute a previously stored search query using its UUID via cURL. This is useful for paginating through results or bookmarking searches. Examples show a successful re-execution and a response for an invalid query ID.

```bash
# Re-execute a stored search query with different pagination
curl -X GET "https://your-wildbook-instance/api/v3/search/search-query-uuid?from=20&size=20" \
  -H "Content-Type: application/json" \
  -b cookies.txt
```

```json
# Response (200 OK):
{
  "success": true,
  "searchQueryId": "search-query-uuid",
  "hits": [
    {"id": "enc-uuid-21", "genus": "Megaptera", "year": 2023},
    {"id": "enc-uuid-22", "genus": "Megaptera", "year": 2023}
  ]
}

# Response (404 Not Found) - invalid query ID:
{
  "error": "invalid searchQueryId search-query-uuid"
}
```

--------------------------------

### GET /api/v3/site-settings

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieve public site configuration settings.

```APIDOC
## GET /api/v3/site-settings

### Description
Retrieve public site configuration settings including enabled features, species configurations, and location definitions.

### Method
GET

### Endpoint
/api/v3/site-settings

### Response
#### Success Response (200)
- **siteName** (string) - Name of the site.
- **species** (array) - List of configured species.
- **iaEnabled** (boolean) - Status of AI features.
```

--------------------------------

### Encounter Management API

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/info.html

Examples of creating, fetching, and interacting with Encounter objects using the Wildbook Javascript API.

```APIDOC
## Encounter Management API

### Description

This section demonstrates how to create and fetch encounter data using the Wildbook Javascript API. It also shows how to retrieve associated images and marked individuals for a given encounter.

### Create and Fetch Single Encounter

Creates and then fetches a single encounter using its catalog number via the REST API.

```javascript
var enc = new wildbook.Model.Encounter({catalogNumber: '4f085ee0-e16e-4a4a-ad5b-6f9e2d0ae289'});
enc.fetch({
    success: function() {
        output(enc.get('guid'));
    }
});
```

### Get Images for Encounter

Retrieves the images associated with a fetched encounter. The images are set to `enc.images` as a Collection of `SinglePhotoVideos`.

```javascript
// Assuming 'enc' is a fetched Encounter object
enc.getImages( function() {
    output(enc.images.models[0].url());
});
```

### Get Marked Individual for Encounter

Retrieves the marked individual associated with a fetched encounter. The individual is set to `enc.individual`.

```javascript
// Assuming 'enc' is a fetched Encounter object
enc.getIndividual( function() {
    output(enc.individual.id);
});
```
```

--------------------------------

### Create and Fetch Encounter (Javascript)

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/info.html

Creates a new Encounter model instance and then fetches its data using the REST API. The success callback logs the encounter's GUID. This demonstrates basic model instantiation and data retrieval.

```javascript
enc = new wildbook.Model.Encounter({catalogNumber: '4f085ee0-e16e-4a4a-ad5b-6f9e2d0ae289'});
enc.fetch({
    success: function() {
        output( enc.get('guid') );
    }
});
```

--------------------------------

### Get Public Site Configuration

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieves public-facing site settings, including enabled features, species lists, and defined location IDs. Does not require authentication.

```bash
curl -X GET "https://your-wildbook-instance/api/v3/site-settings" -H "Content-Type: application/json"
```

--------------------------------

### Initialize Tablesorter with DateTime Format

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/tablesorter/README.md

Demonstrates how to configure the tablesorter plugin to correctly parse and sort DateTime columns. This example specifies the 'pt' (Portuguese) date format.

```javascript
$(document).ready(function()
    {
        $("#myTable").tablesorter( {dateFormat: 'pt'} );
    }
);
```

--------------------------------

### Wildbook API Image Response Examples

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Illustrates typical JSON responses from the Wildbook API for image-related requests, including successful (200 OK) and not found (404 Not Found) scenarios. These responses contain metadata about the image and its annotations.

```json
{
  "success": true,
  "statusCode": 200,
  "url": "/wildbook/images/encounters/enc-uuid/whale_photo.jpg",
  "width": 4000,
  "height": 3000,
  "rotationInfo": {
    "rotation": 0
  },
  "annotations": [
    {
      "id": "ann-uuid-1",
      "encounterId": "enc-uuid-12345",
      "encounterTaxonomy": "Megaptera novaeangliae",
      "trivial": false,
      "x": 150,
      "y": 200,
      "width": 400,
      "height": 300
    },
    {
      "id": "ann-uuid-2",
      "encounterId": "enc-uuid-12345",
      "encounterTaxonomy": "Megaptera novaeangliae",
      "trivial": true,
      "x": 0,
      "y": 0,
      "width": 4000,
      "height": 3000
    }
  ]
}
```

```json
{
  "success": false,
  "statusCode": 404,
  "error": "not found"
}
```

--------------------------------

### Get Encounter Details

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieves the full details of a specific encounter by its unique identifier, including annotations and media assets.

```bash
curl -X GET "https://your-wildbook-instance/api/v3/encounters/enc-uuid-12345" \
  -H "Content-Type: application/json" \
  -b cookies.txt
```

--------------------------------

### Initialize Tablesorter with Sort List

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/tablesorter/README.md

Initializes the tablesorter plugin with a specific sort order. This example configures the table to sort first by the first column (index 0) in ascending order, then by the second column (index 1) in ascending order.

```javascript
$(document).ready(function()
    {
        $("#myTable").tablesorter( {sortList: [[0,0], [1,0]]} );
    }
);
```

--------------------------------

### Get Encounters for Marked Individual (Javascript)

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/info.html

Fetches all encounters associated with a specific MarkedIndividual. The results are stored in the `enc.individual.encounters` collection, and the total count of found encounters is logged. This helps in analyzing an individual's sighting history.

```javascript
enc.individual.getEncounters( function() {
    output( "found " + enc.individual.encounters.models.length + " encounters");
} );
```

--------------------------------

### Get Encounter Images (Javascript)

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/info.html

Fetches the images associated with a previously fetched Encounter object. The images are stored in the `enc.images` collection, and the URL of the first image is logged upon successful retrieval. This showcases how to access related media for an encounter.

```javascript
enc.getImages( function() {
    output( enc.images.models[0].url() );
} );
```

--------------------------------

### Create Deployment Directory Structure

Source: https://github.com/wildmeorg/wildbook/blob/main/devops/README.md

Sets up the required directory hierarchy for the Wildbook deployment environment.

```text
wildbook-dev
|--logs
|--webapps
   |--wildbook
```

--------------------------------

### GET /api/v3/individuals

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieve a list of individuals from the catalog.

```APIDOC
## GET /api/v3/individuals

### Description
Retrieves a list of individuals from the Wildbook catalog. This endpoint supports filtering and pagination to manage large datasets.

### Method
GET

### Endpoint
/api/v3/individuals

### Parameters
#### Query Parameters
- **species_id** (string) - Optional - Filter individuals by species.
- **limit** (integer) - Optional - Maximum number of individuals to return (default: 50).
- **offset** (integer) - Optional - Number of individuals to skip (for pagination).

### Response
#### Success Response (200 OK)
- **individuals** (array) - A list of individual objects.
  - **id** (string) - Unique identifier for the individual.
  - **species_id** (string) - The species of the individual.
  - **name** (string) - Common name or identifier for the individual.
  - **created_at** (string) - Timestamp when the individual was added.

#### Response Example
```json
{
  "individuals": [
    {
      "id": "ind_abc123",
      "species_id": "tiger",
      "name": "Raja",
      "created_at": "2023-01-15T09:30:00Z"
    },
    {
      "id": "ind_def456",
      "species_id": "tiger",
      "name": "Shakti",
      "created_at": "2023-02-20T11:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Initialize Wildbook and Execute Code Snippets (Javascript)

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/info.html

Initializes the Wildbook application and sets up an event listener for elements with the class 'exec'. Clicking these elements executes the contained Javascript code using `eval()` and displays the output. This provides an interactive way to test code snippets.

```javascript
$(document).ready(function() {
    wildbook.init();
});

$('.exec').click(function() {
    $('#output').html('');
    var js = this.innerHTML;
    console.info("eval'ing: %s", js);
    eval(js);
});

function output(s) {
    $('#output').html(s);
    console.log('output: %o', s);
}
```

--------------------------------

### Occurrences - Get Occurrence Details API Request

Source: https://context7.com/wildmeorg/wildbook/llms.txt

This snippet demonstrates how to fetch complete information about a specific occurrence using its UUID. It sends a GET request to the occurrences endpoint. The response includes details like group size, location, and a list of associated encounters.

```bash
curl -X GET "https://your-wildbook-instance/api/v3/occurrences/occ-uuid-12345" \
  -H "Content-Type: application/json" \
  -b cookies.txt
```

--------------------------------

### Build and Deploy Wildbook WAR File

Source: https://github.com/wildmeorg/wildbook/blob/main/devops/README.md

Compiles the Java project into a WAR file using Maven and extracts it into the deployment directory for the Tomcat server.

```bash
mvn clean install
cd ~/wildbook-dev/webapps/wildbook
jar -xvf /code/directory/Wildbook/target/wildbook-X.Y.Z.war
```

--------------------------------

### Access API Documentation

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Provides methods to access interactive Swagger UI documentation or download the raw OpenAPI YAML specification for integration with external tools.

```bash
curl -X GET "https://your-wildbook-instance/api/v3/docs/openapi.yaml" -H "Accept: application/x-yaml" --output openapi.yaml
```

--------------------------------

### GET /api/v3/user

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieves profile information for the currently authenticated user.

```APIDOC
## GET /api/v3/user

### Description
Retrieve profile information for the currently authenticated user, including their organizations and admin status.

### Method
GET

### Endpoint
/api/v3/user

### Response
#### Success Response (200)
- **id** (string) - User UUID
- **username** (string) - User email
- **fullName** (string) - User full name
- **isAdmin** (boolean) - Admin status

#### Response Example
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "researcher@example.com",
  "fullName": "Jane Researcher",
  "isAdmin": false
}
```

--------------------------------

### Media Assets - Get Asset Info API Request

Source: https://context7.com/wildmeorg/wildbook/llms.txt

This snippet demonstrates how to retrieve information about a specific media asset using its ID. It sends a GET request to the media-assets endpoint. The response provides details such as the asset's URL, dimensions, rotation information, and any associated annotations.

```bash
curl -X GET "https://your-wildbook-instance/api/v3/media-assets/12345" \
  -H "Content-Type: application/json" \
  -b cookies.txt
```

--------------------------------

### GET /api/v3/user/{uuid}

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieves profile information for a specific user by their UUID.

```APIDOC
## GET /api/v3/user/{uuid}

### Description
Retrieve profile information for a specific user by their UUID. Non-admin users will have email addresses hidden when viewing other users.

### Method
GET

### Endpoint
/api/v3/user/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the user

### Response
#### Success Response (200)
- **id** (string) - User UUID
- **username** (string) - User email (hidden for non-admins)
- **fullName** (string) - User full name

#### Response Example
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "researcher@example.com",
  "fullName": "Jane Researcher"
}
```

--------------------------------

### Run Full Maven Build

Source: https://github.com/wildmeorg/wildbook/blob/main/docs/plans/2026-01-30-coco-export-implementation.md

This command executes a full Maven compile operation on the project. It changes the directory to the project root and then runs 'mvn compile', displaying the last 20 lines of the output. A successful build is indicated by 'BUILD SUCCESS'.

```bash
cd /mnt/c/Wildbook-clean2 && mvn compile -q 2>&1 | tail -20

```

--------------------------------

### Useful Git Commands for Local Development in Wildbook

Source: https://github.com/wildmeorg/wildbook/blob/main/README.md

This section provides a list of commonly used Git commands for managing local changes during Wildbook development. These commands help in tracking modifications, staging files for commit, and reviewing differences.

```bash
git log
git status
git diff --staged
git add <filename>
git commit
```

--------------------------------

### Individuals - Get Individual Details API Request

Source: https://context7.com/wildmeorg/wildbook/llms.txt

This snippet shows how to retrieve detailed information about a specific marked individual using its UUID. It sends a GET request to the individuals endpoint. The response contains the individual's profile, including names, genus, sex, encounter counts, and sighting history.

```bash
curl -X GET "https://your-wildbook-instance/api/v3/individuals/indiv-uuid-12345" \
  -H "Content-Type: application/json" \
  -b cookies.txt
```

--------------------------------

### GET /api/v3/bulk-import/{taskId}

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieve the status and details of a specific bulk import task.

```APIDOC
## GET /api/v3/bulk-import/{taskId}

### Description
Retrieve the status and details of a bulk import task, including progress, errors, and created encounter IDs.

### Method
GET

### Endpoint
/api/v3/bulk-import/{taskId}

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of the import task.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **task** (object) - Contains task details including status, error counts, and created IDs.

#### Response Example
{
  "success": true,
  "statusCode": 200,
  "task": {
    "id": "import-task-uuid",
    "status": "complete",
    "numberEncounters": 150
  }
}
```

--------------------------------

### Commit New Servlet Implementation

Source: https://github.com/wildmeorg/wildbook/blob/main/docs/plans/2026-01-30-coco-export-implementation.md

Command to stage and commit the newly created servlet file to the version control system.

```bash
git add src/main/java/org/ecocean/servlet/export/EncounterSearchExportCOCO.java
git commit -m "feat: add EncounterSearchExportCOCO servlet"
```

--------------------------------

### Occurrences - Get Occurrence Details

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieve complete information about an occurrence including all associated encounters observed during that sighting event.

```APIDOC
## GET /api/v3/occurrences/{id}

### Description
Retrieve complete information about an occurrence including all associated encounters observed during that sighting event.

### Method
GET

### Endpoint
/api/v3/occurrences/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the occurrence.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **statusCode** (integer) - The HTTP status code.
- **id** (string) - The unique identifier of the occurrence.
- **groupSize** (integer) - The number of individuals observed in the group.
- **decimalLatitude** (number) - The latitude of the observation.
- **decimalLongitude** (number) - The longitude of the observation.
- **locationId** (string) - An identifier for the location.
- **encounters** (array) - A list of encounters associated with the occurrence.
- **comments** (string) - Additional comments about the occurrence.

#### Response Example
```json
{
  "success": true,
  "statusCode": 200,
  "id": "occ-uuid-12345",
  "groupSize": 5,
  "decimalLatitude": 21.2743,
  "decimalLongitude": -157.8255,
  "locationId": "Hawaii",
  "encounters": [
    {"id": "enc-uuid-1"},
    {"id": "enc-uuid-2"},
    {"id": "enc-uuid-3"}
  ],
  "comments": "Pod of 5 humpbacks observed feeding together"
}
```
```

--------------------------------

### Initialize Encounter Data Fetching

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/table.html

Initializes the application state and triggers the encounter data fetch process using the wildbook collection API.

```javascript
$(document).ready(function() { wildbook.init(function() { tableInit(); fetchData(); }); }); function fetchData() { encs = new wildbook.Collection.Encounters(); encs.fetch({ success: function() { tableShow(); } }); }
```

--------------------------------

### Git Commands for Forking and Branching in Wildbook

Source: https://github.com/wildmeorg/wildbook/blob/main/README.md

This snippet details essential Git commands for contributing to the Wildbook project. It includes cloning the forked repository, setting up the upstream remote, creating and switching to feature branches, and pulling updates from the upstream main branch.

```bash
git clone https://github.com/USERNAME/Wildbook
cd Wildbook
git remote add upstream https://github.com/WildMeOrg/Wildbook
git fetch upstream
git checkout main
git checkout ISSUENUMBER-FEATUREBRANCHNAME
git pull upstream main
```

--------------------------------

### Individuals - Get Individual Details

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieve complete information about a marked individual including all associated encounters, names, and identification history.

```APIDOC
## GET /api/v3/individuals/{id}

### Description
Retrieve complete information about a marked individual including all associated encounters, names, and identification history.

### Method
GET

### Endpoint
/api/v3/individuals/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the individual.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **statusCode** (integer) - The HTTP status code.
- **id** (string) - The unique identifier of the individual.
- **individualID** (string) - The unique identifier for the individual.
- **names** (object) - A dictionary of names associated with the individual.
- **genus** (string) - The genus of the species.
- **specificEpithet** (string) - The specific epithet of the species.
- **sex** (string) - The sex of the individual.
- **numberEncounters** (integer) - The total number of encounters associated with the individual.
- **dateFirstIdentified** (string) - The date the individual was first identified.
- **dateTimeLatestSighting** (string) - The date and time of the latest sighting.
- **encounters** (array) - A list of encounters associated with the individual.
- **comments** (string) - Additional comments about the individual.

#### Response Example
```json
{
  "success": true,
  "statusCode": 200,
  "id": "indiv-uuid-12345",
  "individualID": "indiv-uuid-12345",
  "names": {
    "Nickname": "Splash",
    "Alternate ID": "HI-2019-0042"
  },
  "genus": "Megaptera",
  "specificEpithet": "novaeangliae",
  "sex": "female",
  "numberEncounters": 15,
  "dateFirstIdentified": "2019-03-15",
  "dateTimeLatestSighting": "2024-01-15T10:30:00Z",
  "encounters": [
    {
      "id": "enc-uuid-1",
      "date": "2024-01-15",
      "locationId": "Hawaii"
    }
  ],
  "comments": "Distinctive fluke pattern with white markings"
}
```
```

--------------------------------

### Encounters - Get Encounter Details

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieve complete details of a specific encounter including all associated data, annotations, and media assets.

```APIDOC
## GET /api/v3/encounters/{encounterId}

### Description
Retrieve complete details of a specific encounter including all associated data, annotations, and media assets.

### Method
GET

### Endpoint
/api/v3/encounters/{encounterId}

### Parameters
#### Path Parameters
- **encounterId** (string) - Required - The unique identifier of the encounter to retrieve.

### Request Example
```bash
curl -X GET "https://your-wildbook-instance/api/v3/encounters/enc-uuid-12345" \
  -H "Content-Type: application/json" \
  -b cookies.txt
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **statusCode** (integer) - The HTTP status code.
- **id** (string) - The unique identifier for the encounter.
- **catalogNumber** (string) - The catalog number of the encounter.
- **genus** (string) - The genus of the species.
- **specificEpithet** (string) - The specific epithet of the species.
- **taxonomy** (string) - The full taxonomic classification.
- **year** (integer) - The year the encounter occurred.
- **month** (integer) - The month the encounter occurred.
- **day** (integer) - The day the encounter occurred.
- **hour** (integer) - The hour the encounter occurred.
- **minutes** (string) - The minutes of the encounter.
- **decimalLatitude** (number) - The latitude of the encounter location.
- **decimalLongitude** (number) - The longitude of the encounter location.
- **locationId** (string) - Identifier for the location.
- **verbatimLocality** (string) - The verbatim locality of the encounter.
- **sex** (string) - The sex of the individual.
- **lifeStage** (string) - The life stage of the individual.
- **behavior** (string) - The observed behavior.
- **country** (string) - The country where the encounter occurred.
- **state** (string) - The state of the encounter record (e.g., "approved").
- **individualId** (string) - The ID of the individual if assigned.
- **occurrenceId** (string) - The occurrence ID if assigned.
- **annotations** (array) - List of annotations for the encounter.
  - **id** (string) - The unique identifier for the annotation.
  - **mediaAssetId** (integer) - The ID of the media asset the annotation is associated with.
  - **iaClass** (string) - The class or type of annotation.
- **submitters** (array) - List of users who submitted the encounter.
  - **id** (string) - The user's ID.
  - **fullName** (string) - The full name of the submitter.
- **dwcDateAdded** (string) - The date and time the record was added in Darwin Core format.

#### Response Example (200 OK)
```json
{
  "success": true,
  "statusCode": 200,
  "id": "enc-uuid-12345",
  "catalogNumber": "enc-uuid-12345",
  "genus": "Megaptera",
  "specificEpithet": "novaeangliae",
  "taxonomy": "Megaptera novaeangliae",
  "year": 2024,
  "month": 1,
  "day": 15,
  "hour": 10,
  "minutes": "30",
  "decimalLatitude": 21.2743,
  "decimalLongitude": -157.8255,
  "locationId": "Hawaii",
  "verbatimLocality": "Maui, Hawaii - offshore",
  "sex": "female",
  "lifeStage": "adult",
  "behavior": "breaching",
  "country": "United States",
  "state": "approved",
  "individualId": "indiv-uuid-if-assigned",
  "occurrenceId": "occ-uuid-if-assigned",
  "annotations": [
    {
      "id": "ann-uuid-1",
      "mediaAssetId": 12345,
      "iaClass": "whale_fluke"
    }
  ],
  "submitters": [
    {
      "id": "user-uuid",
      "fullName": "Jane Researcher"
    }
  ],
  "dwcDateAdded": "2024-01-15T10:35:00Z"
}
```

#### Error Response (404 Not Found)
- **success** (boolean) - Indicates if the operation was successful.
- **statusCode** (integer) - The HTTP status code.
- **error** (string) - A message indicating the resource was not found.

#### Response Example (404 Not Found)
```json
{
  "success": false,
  "statusCode": 404,
  "error": "not found"
}
```
```

--------------------------------

### List Bulk Import Tasks

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Fetches a list of all bulk import tasks accessible to the authenticated user. Admins can view all system tasks, while regular users see their own.

```bash
curl -X GET "https://your-wildbook-instance/api/v3/bulk-import" -H "Content-Type: application/json" -b cookies.txt
```

--------------------------------

### Wildbook API v3 Overview

Source: https://context7.com/wildmeorg/wildbook/llms.txt

This section provides an overview of the Wildbook API v3, including authentication methods and general usage patterns.

```APIDOC
## Wildbook API v3 Overview

### Description
The Wildbook API v3 allows programmatic interaction with the Wildbook platform for submitting wildlife encounter reports, managing animal identification catalogs, performing searches, and exporting data. It utilizes session-based authentication via JSESSIONID cookies.

### Authentication
Session-based authentication is required. Obtain a session cookie (JSESSIONID) by logging in through the web interface or via a dedicated authentication endpoint (if available).

### Base URL
The base URL for API v3 endpoints is typically `/api/v3` relative to the Wildbook instance.

### Media Upload
Media files (photos) should be uploaded using the ResumableUpload mechanism before creating an encounter.

### Data Formats
Data can be exported in standard formats such as CSV and COCO.
```

--------------------------------

### Media Assets - Get Asset Info

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieve information about a specific media asset including its URL, dimensions, rotation info, and all associated annotations.

```APIDOC
## GET /api/v3/media-assets/{id}

### Description
Retrieve information about a specific media asset including its URL, dimensions, rotation info, and all associated annotations.

### Method
GET

### Endpoint
/api/v3/media-assets/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the media asset.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **statusCode** (integer) - The HTTP status code.
- **id** (integer) - The unique identifier of the media asset.
- **url** (string) - The URL of the media asset.
- **width** (integer) - The width of the media asset.
- **height** (integer) - The height of the media asset.
- **rotation** (integer) - The rotation information of the media asset.
- **annotations** (array) - A list of annotations associated with the media asset.

#### Response Example
```json
{
  "success": true,
  "statusCode": 200,
  "id": 12345,
  "url": "https://your-wildbook-instance/media/12345.jpg",
  "width": 1920,
  "height": 1080,
  "rotation": 0,
  "annotations": [
    {"id": "ann-uuid-1", "iaClass": "whale_fluke"}
  ]
}
```
```

--------------------------------

### Initialize Image Annotation Tools

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/itest.html

Sets up event listeners for mouse interactions on an image element, including dragging, rotating, and scaling spots. It initializes the ImageTools object with specific styles and event handlers.

```javascript
function setTool() {
  var opts = {
    el: document.getElementById('fluke-img'),
    eventListeners: {
      contextmenu: function(ev) { t._addingSpot = false; ev.preventDefault(); ev.stopPropagation(); },
      mousemove: function(ev) { /* Logic for dragging, rotating, scaling */ },
      mousedown: function(ev) { /* Logic for selecting or adding spots */ },
      mouseup: function(ev) { /* Logic for finalizing spot placement */ }
    }
  };
  t = new ImageTools(opts);
  t.spots = [];
  t._mode = 4;
}
```

--------------------------------

### Get Bulk Import Task Status

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Retrieves the status, progress, and error details of a specific bulk import task using its unique identifier. Requires authentication via cookies.

```bash
curl -X GET "https://your-wildbook-instance/api/v3/bulk-import/import-task-uuid" -H "Content-Type: application/json" -b cookies.txt
```

--------------------------------

### Initialize Navigation and Language Selection UI

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/resources/servletResponseTemplate.htm

Handles the initialization of dropdown menus with hover effects and sets up event listeners for language selection. It uses cookies to persist the user's language choice and triggers a page reload to apply changes.

```javascript
document.addEventListener('DOMContentLoaded', function () { document.querySelectorAll('.navbar .dropdown').forEach(function (dropdown) { dropdown.addEventListener('mouseenter', function () { var dropdownMenu = this.querySelector('.dropdown-menu'); if (dropdownMenu) { dropdownMenu.style.display = 'block'; setTimeout(function () { dropdownMenu.style.opacity = 1; }, 250); } }); dropdown.addEventListener('mouseleave', function () { var dropdownMenu = this.querySelector('.dropdown-menu'); if (dropdownMenu) { setTimeout(function () { dropdownMenu.style.display = 'none'; dropdownMenu.style.opacity = 0; }, 100); } }); }); document.querySelectorAll('.lang_selector').forEach(function (element) { var langCode = element.getAttribute('data-lang'); var imgUrl = "/images/flag_" + langCode + ".gif"; element.addEventListener('click', function (event) { selectItem(element, langCode, imgUrl); }); }); }); function selectItem(element, langCode, imgUrl) { document.cookie = "wildbookLangCode=" + encodeURIComponent(langCode) + "; path=/"; location.reload(true); }
```

--------------------------------

### Get Marked Individual from Encounter (Javascript)

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/info.html

Retrieves the MarkedIndividual associated with a given Encounter. The individual's data is assigned to the `enc.individual` property, and its ID is logged upon successful retrieval. This is useful for linking encounters to specific individuals.

```javascript
enc.getIndividual( function() {
    output( enc.individual.id );
} );
```

--------------------------------

### Wildbook Javascript Overview

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/info.html

Overview of the Wildbook Javascript classes and their underlying architecture.

```APIDOC
## Wildbook Javascript Overview

### Description

This section provides an overview of the Javascript classes available in Wildbook. These classes are built upon Backbone.js and are designed to mimic Java classes. Key implemented classes include Encounter.js, MarkedIndividual.js, and SinglePhotoVideo.js, all inheriting from a common Base.js class.

### Key Classes

*   **Encounter.js**: Represents an encounter with an individual.
*   **MarkedIndividual.js**: Represents a marked individual.
*   **SinglePhotoVideo.js**: Represents a single photo or video associated with an encounter.
*   **Base.js**: The common base class for all other Javascript classes.

### Initialization

To initialize Wildbook, use the following code:

```javascript
$(document).ready(function() {
    wildbook.init();
});
```
```

--------------------------------

### Pathfinding Algorithm in JavaScript

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/itest.html

Implements a pathfinding algorithm that explores possible paths between two points in image data. It considers 'skipped' pixels and calculates distances to find the best path, returning it or false if no path is found. Dependencies include a 'bestPath' function and distance calculation.

```javascript
function bestPath(imageData, p1, p2, skipped) {
  var bestScore = false;
  var bPath = false;
  var thisPt = p1;
  var r = 10;
  for (var y = -r; y < r + 1; y++) {
    for (var x = -r; x < r + 1; x++) {
      if ((x == 0) && (y == 0)) continue;
      var s = skipped;
      var path = bestPath(imageData, [p1[0] + x, p1[1] + y], p2, s);
      if (!path || !path.length) continue;
      var d = t.dist(path[path.length - 1][0], path[path.length - 1][1], p2[0], p2[1]);
      if (!bestScore || (d < bestScore)) {
        bestScore = d;
        bPath = path;
      }
    }
  }
  if (bPath) {
    if (thisPt) bPath.unshift(thisPt);
    return bPath;
  } else {
    return false;
  }
}
```

--------------------------------

### Bash Commands for Compilation and Commit

Source: https://github.com/wildmeorg/wildbook/blob/main/docs/plans/2026-01-30-coco-export-implementation.md

This section provides the necessary bash commands to compile the Java code using Maven and to commit the changes to the Git repository. The compilation command includes options for quiet output and to include all modules, while the commit command stages the modified file and creates a commit with a descriptive message.

```Bash
cd /mnt/c/Wildbook-clean2 && mvn compile -q -pl . -am 2>&1 | head -30
```

```Bash
git add src/main/java/org/ecocean/export/EncounterCOCOExportFile.java
git commit -m "feat: add data collection methods for COCO export"
```

--------------------------------

### Execute Maven Unit Tests

Source: https://github.com/wildmeorg/wildbook/blob/main/src/test/README.md

Commands to run specific backend unit tests using Maven without triggering a full compilation.

```bash
mvn test
mvn test -Dtest=TestClass1,TestClass2
mvn test -Dtest=TestClass#method
```

--------------------------------

### Table Pagination and Visibility Management

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/table.html

The pageTable function manages row visibility based on a start index and count, while pageNudge handles navigation offsets. These functions interact with DOM elements to update table views and synchronize with UI slider components.

```javascript
function pageTable(start, howMany) {
  $('.visible').removeClass('visible');
  var ends = start + howMany;
  for (var i = start ; i < ends ; i++) {
    if (!$('#table-body').children()[i]) continue;
    if ($($('#table-body').children()[i]).hasClass('nof')) {
      ends++;
      continue;
    }
    $('#table-body').children()[i].className = 'visible';
  }
}

function pageNudge(n) {
  pstart += n;
  if (pstart < 0) pstart = 0;
  if (pstart > (countTotal - perPage)) pstart = countTotal - perPage;
  pageTable(pstart, perPage);
  if (hasSlider) $('#slider').slider('option', 'value', 100 - (pstart / (countTotal - perPage)) * 100);
}
```

--------------------------------

### POST /api/v3/login

Source: https://context7.com/wildmeorg/wildbook/llms.txt

Authenticates a user and establishes a session using Apache Shiro, returning a session cookie.

```APIDOC
## POST /api/v3/login

### Description
Authenticates a user and establishes a session. The API uses session-based authentication with cookies (JSESSIONID) for subsequent authenticated requests.

### Method
POST

### Endpoint
/api/v3/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's email address
- **password** (string) - Required - The user's password

### Request Example
{
  "username": "researcher@example.com",
  "password": "securePassword123"
}

### Response
#### Success Response (200)
- **success** (boolean) - Status of the login attempt
- **id** (string) - User UUID
- **username** (string) - User email
- **fullName** (string) - User full name

#### Response Example
{
  "success": true,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "researcher@example.com",
  "fullName": "Jane Researcher"
}
```

--------------------------------

### Image Tracing Function in JavaScript

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/itest.html

The `MEHtrace` function initiates an image tracing process using the `crawl` function. It then displays the resulting image data using `fctx.putImageData` and logs the traced points to the console. This function serves as a high-level entry point for the tracing functionality.

```javascript
function MEHtrace(imageData, p1, p2) {
  var pts = crawl(imageData, p1, p2, 3);
  fctx.putImageData(imageData, 0, 0);
  console.log(pts);
}
```

--------------------------------

### Individuals - Create New Individual API Request

Source: https://context7.com/wildmeorg/wildbook/llms.txt

This snippet demonstrates how to create a new marked individual record using the Wildbook API. It requires authentication and sends a POST request with individual details in JSON format. The response includes the new individual's ID or an error message.

```bash
curl -X POST "https://your-wildbook-instance/api/v3/individuals" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "submissionId": "upload-session-uuid",
    "name": "Splash",
    "genus": "Megaptera",
    "specificEpithet": "novaeangliae",
    "sex": "female",
    "comments": "Distinctive fluke pattern with white markings"
  }'
```

--------------------------------

### Manage Table Pagination and Interaction

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/table.html

Handles table row rendering, pagination logic, and keyboard/wheel event listeners for navigating large encounter datasets.

```javascript
function pageTable(start, howMany) { pstart = start; $('.visible').removeClass('visible'); $('#table-body tr').slice(start, start + howMany).addClass('visible'); } function pageNudge(delta) { var next = Math.max(0, Math.min(countTotal - perPage, pstart + delta)); if (next != pstart) pageTable(next, perPage); }
```

--------------------------------

### Marked Individual and Collection Queries

Source: https://github.com/wildmeorg/wildbook/blob/main/src/main/webapp/javascript/classes/info.html

Demonstrates fetching Encounters for a MarkedIndividual and performing collection queries using JDOQL or field/value pairs.

```APIDOC
## Marked Individual and Collection Queries

### Description

This section covers how to retrieve encounters associated with a marked individual and how to perform advanced queries on collections of Marked Individuals using the Wildbook Javascript API.

### Get Encounters for Marked Individual

Retrieves all encounters for a given marked individual. The encounters are set to `enc.individual.encounters` as a Collection of Encounters.

```javascript
// Assuming 'enc' is a fetched Encounter object with an 'individual' property
enc.individual.getEncounters( function() {
    output("found " + enc.individual.encounters.models.length + " encounters");
});
```

### Collection Fetch with JDOQL

Demonstrates overriding the standard `Collection.fetch()` to support JDOQL queries for the REST API.

```javascript
var inds = new wildbook.Collection.MarkedIndividuals();
inds.fetch({
    jdoql: 'WHERE individualID.startsWith("n")',
    success: function(mods) {
        output("found " + mods.length + " individual");
    }
});
```

### Collection Fetch with Field/Value Query

Shows an alternative method for querying collections using field and value pairs.

```javascript
var inds = new wildbook.Collection.MarkedIndividuals();
inds.fetch({
    fields: {
        sex: "female",
        seriesCode: "None"
    },
    success: function(mods) {
        output("found " + mods.length + " individuals");
    }
});
```
```