TaxonWorks API Documentation

version v1
baseUri https://{host}/api/{version}
protocols HTTPS
mediaType application/json

Introduction

This is the documentation for external TaxonWorks API endpoints. Documentation source is at https://github.com/SpeciesFileGroup/taxonworks_api. In brief this allows users to access data curated in a copy of TaxonWorks via a user or project (anonymous) level token.

Servers with live APIs

Each instance of TaxonWorks serves its own API. Add your instance to this list with a pull request.

Species File Group (production) - A production instance of TaxonWorks hosted by the Species File Group (SFG).
SFG Sandbox (sandbox) - A SFG sandbox, may/not be live.
SFG Sandfly (sandbox) - A SFG sandbox, may/not be live.

Roadmap

Our approach:

v1 (current)
- Goal is to expose existing internal endpoints that the application is built upon
- Endpoints are practical, in that they are nearly being used in interfaces, but not necessarily optimized
- Largely JSON based, and are derived from Rails conventions
v2 (planned)
- Optimize existing routes, remove nestedness where it makes sense
- Increase standardization of traits (params) across endpoints
- Explore delayed responses/ticketing system for long running queries
v3 (planned)
- Integrate caching other optimizations optimization
- Perhaps move to a fully cached solution, using GraphQL
- May move cache to a graph DB or other flattened indexer

Running an api-console

This both lets you read the API documentation and experiment directly therein against a local rails server (localhost:3000).

You must have a TaxonWorks instance running at localhost:3000 (rails s, see install_taxonworks) before sending API requests though the console.

Use npm install if you haven't already. Then just run npm start -- --open (-- --open is optional, it will make your browser open the URL the console is being served from).

Once it is ready to explore you should see something like this:

$ npm start -- --open

(OUTPUT OMITTED)

API console build ready.
Thanks for using our API tools!

Files in this directory are available under the following URLs
      applications: http://127.0.0.1:8081

NOTE: It might display a white screen when the browser opens the URL (specially true with Firefox, Chrome seems inmune to this problem). Refresh a few times until it shows the documentation.

Other endpoints

From your terminal within the source directory (not this repo) use rake routes to get a list of all endpoints. Endpoints are defined as Rails routes in /config/routes/api*.

Types

TaxonName

Properties

cached

Genus-species combination for genus and lower, monomial for higher. The string has NO html, and no author/year.

Property	Value
required	true
type	string

cached_author_year

Author and year string with parentheses where necessary, i.e. with context of present placement for ICZN.

Property	Value
required	true
type	union

cached_html

As in cached but with tags.

Property	Value
required	true
type	string

etymology

The derivation and history of the name in written form.

Property	Value
required	true
type	string

feminine_name

Species name which are adjective or participle change depending on the gender of the genus. 3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification. The gender of a genus also designated as a taxon_name_classification.

Property	Value
required	true
type	string

TaxonName instance identifier

Property	Value
required	true
type	number
examples	`25225`

masculine_name

Property	Value
required	true
type	string

neuter_name

Property	Value
required	true
type	string

name

The fully latinized string (monomimial) of a code governed taxonomic biological name not applicable for Combinations, they are derived from their pieces.

Property	Value
required	true
type	string
examples	`asymmetricus`

name_string

The current name/combination with author year, without HTML.

Property	Value
required	true
type	string

nomenclatural_code

The name of the nomenclatural code, as a short symbol (:iczn, :icn), or nil

Property	Value
required	true
type	union

original_combination

The name in original combination, with author year, with HTML.

Property	Value
required	true
type	string

parent_id

The id of the parent taxon. The parent child relationship is exclusively organizational. All statuses and relationships of a taxon name must be explicitly defined via taxon name relationships or classifications. The parent of a taxon name can be thought of as "the place where you'd find this name in a hierarchy if you knew literally nothing else about that name." In practice read each monomial in the name (protonym or combination) from right to left, the parent is the parent of the last monomial read. There are 3 simple rules for determening the parent of a Protonym or Combination:

the parent must always be at least one rank higher than the target names rank
the parent of a synonym (any sense) is the parent of the synonym's valid name
the parent of a combination is the parent of the highest ranked monomial in the epithet (almost always the parent of the genus)

Property	Value
required	true
type	integer
examples	`2`

project_id

The project ID

Property	Value
required	true
type	integer

rank_string

Rank (Kindom, Phylum...) as a string, like {NomenclaturalRank::Iczn::SpeciesGroup::Species}

Property	Value
required	true
type	string

type

The subclass of this taxon name, e.g. Protonym or Combination.

Property	Value
required	true
type	string

verbatim_author

The verbatim author string as provided ? is not post-filled in when Source is referenced !?

Property	Value
required	true
type	string

verbatim_name

A representation of what the combination (fully spelled out) or protonym (monomial) looked like in its originating publication. The sole purpose of this string is to represent visual differences from what is recorded in the latinized version of the name (Protonym#name, Combination#cached) from what was originally transcribed. This string should NOT include the author year (see verbatim_author and year_of_publication for those data).

Property	Value
required	true
type	string

year_of_publication

Sensu ICZN - the 4 digit year when this name was published, i.e. made available. Not the publishers date stamped on the title page, but the actual date of publication. Precedence for taxon name publication year is TaxonName#year_of_publication, Source#year, Source#stated_year.

Property	Value
required	true
type	integer
examples	`nil`

TYPE DEFINITION

{
  "name": "TaxonName",
  "type": "object",
  "properties": [
    {
      "type": "string",
      "name": "cached",
      "displayName": "cached",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Genus-species combination for genus and lower, monomial for higher. The string has NO html, and no author/year.\n",
      "key": "cached"
    },
    {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "nil"
        }
      ],
      "type": "union",
      "name": "cached_author_year",
      "displayName": "cached_author_year",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Author and year string with parentheses where necessary, i.e. with context of present placement for ICZN.\n",
      "fixedFacets": {
        "description": "Author and year string with parentheses where necessary, i.e. with context of present placement for ICZN.\n"
      },
      "key": "cached_author_year"
    },
    {
      "type": "string",
      "name": "cached_html",
      "displayName": "cached_html",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "As in `cached` but with <i></i> tags.\n",
      "key": "cached_html"
    },
    {
      "type": "string",
      "name": "etymology",
      "displayName": "etymology",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The derivation and history of the name in written form.\n",
      "key": "etymology"
    },
    {
      "type": "string",
      "name": "feminine_name",
      "displayName": "feminine_name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Species name which are adjective or participle change depending on the gender of the genus.\n3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification.\nThe gender of a genus also designated as a taxon_name_classification.\n",
      "key": "feminine_name"
    },
    {
      "type": "number",
      "name": "id",
      "displayName": "id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "TaxonName instance identifier",
      "examples": [
        {
          "value": "25225",
          "strict": true,
          "name": null,
          "structuredValue": 25225
        }
      ],
      "key": "id"
    },
    {
      "type": "string",
      "name": "masculine_name",
      "displayName": "masculine_name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Species name which are adjective or participle change depending on the gender of the genus.\n3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification.\nThe gender of a genus also designated as a taxon_name_classification.\n",
      "key": "masculine_name"
    },
    {
      "type": "string",
      "name": "neuter_name",
      "displayName": "neuter_name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Species name which are adjective or participle change depending on the gender of the genus.\n3 fields provide alternative species spelling. The part_of_speech is designated as a taxon_name_classification.\nThe gender of a genus also designated as a taxon_name_classification.\n",
      "key": "neuter_name"
    },
    {
      "type": "string",
      "name": "name",
      "displayName": "name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The fully latinized string (monomimial) of a code governed taxonomic biological name not\napplicable for Combinations, they are derived from their pieces.\n",
      "examples": [
        {
          "value": "asymmetricus",
          "strict": true,
          "name": null,
          "structuredValue": "asymmetricus"
        }
      ],
      "key": "name"
    },
    {
      "type": "string",
      "name": "name_string",
      "displayName": "name_string",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The current name/combination with author year, without HTML.\n",
      "key": "name_string"
    },
    {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "nil"
        }
      ],
      "type": "union",
      "name": "nomenclatural_code",
      "displayName": "nomenclatural_code",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The name of the nomenclatural code, as a short symbol (:iczn, :icn), or nil\n",
      "fixedFacets": {
        "description": "The name of the nomenclatural code, as a short symbol (:iczn, :icn), or nil\n"
      },
      "key": "nomenclatural_code"
    },
    {
      "type": "string",
      "name": "original_combination",
      "displayName": "original_combination",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The name in original combination, with author year, with HTML.\n",
      "key": "original_combination"
    },
    {
      "type": "integer",
      "name": "parent_id",
      "displayName": "parent_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The id of the parent taxon. The parent child relationship is exclusively organizational. All statuses and relationships\nof a taxon name must be explicitly defined via taxon name relationships or classifications. The parent of a taxon name\ncan be thought of as  \"the place where you'd find this name in a hierarchy if you knew literally *nothing* else about that name.\"\nIn practice read each monomial in the name (protonym or combination) from right to left, the parent is the parent of the last monomial read.\nThere are 3 simple rules for determening the parent of a Protonym or Combination:\n  1) the parent must always be at least one rank higher than the target names rank\n  2) the parent of a synonym (any sense) is the parent of the synonym's valid name\n  3) the parent of a combination is the parent of the highest ranked monomial in the epithet (almost always the parent of the genus)\n",
      "examples": [
        {
          "value": "2",
          "strict": true,
          "name": null,
          "structuredValue": 2
        }
      ],
      "key": "parent_id"
    },
    {
      "type": "integer",
      "name": "project_id",
      "displayName": "project_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The project ID\n",
      "key": "project_id"
    },
    {
      "type": "string",
      "name": "rank_string",
      "displayName": "rank_string",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Rank (Kindom, Phylum...) as a string, like {NomenclaturalRank::Iczn::SpeciesGroup::Species}\n",
      "key": "rank_string"
    },
    {
      "type": "string",
      "name": "type",
      "displayName": "type",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The subclass of this taxon name, e.g. Protonym or Combination.\n",
      "key": "type"
    },
    {
      "type": "string",
      "name": "verbatim_author",
      "displayName": "verbatim_author",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "The verbatim author string as provided ? is not post-filled in when Source is referenced !?\n",
      "key": "verbatim_author"
    },
    {
      "type": "string",
      "name": "verbatim_name",
      "displayName": "verbatim_name",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "A representation of what the combination (fully spelled out) or protonym (monomial) *looked like* in its originating publication.\nThe sole purpose of this string is to represent visual differences from what is recorded in the\nlatinized version of the name (Protonym#name, Combination#cached) from what was originally transcribed.\nThis string should NOT include the author year (see verbatim_author and year_of_publication for those data).\n",
      "key": "verbatim_name"
    },
    {
      "type": "integer",
      "name": "year_of_publication",
      "displayName": "year_of_publication",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Sensu ICZN - the 4 digit year when this name was published, i.e. made available. Not the publishers date stamped on the title page,\nbut the actual date of publication. Precedence for taxon name publication year is TaxonName#year_of_publication, Source#year, Source#stated_year.\n",
      "examples": [
        {
          "value": "nil",
          "strict": true,
          "name": null,
          "structuredValue": "nil"
        }
      ],
      "key": "year_of_publication"
    }
  ]
}

TaxonNameAutocomplete

Properties

TaxonName instance identifier

Property	Value
required	true
type	number
examples	`11877`

label

Plaintext label for the taxon name comprised of both scientific name and authorship.

Property	Value
required	true
type	string
examples	`Jivarus Giglio-Tos, 1898`

label_html

HTML-formatted label for the taxon name comprised of both scientific name and authorship.

Property	Value
required	true
type	string
examples	`Jivarus Giglio-Tos, 1898 genus Jivarini Jivarus`

TYPE DEFINITION

{
  "name": "TaxonNameAutocomplete",
  "type": "object",
  "properties": [
    {
      "type": "number",
      "name": "id",
      "displayName": "id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "TaxonName instance identifier",
      "examples": [
        {
          "value": "11877",
          "strict": true,
          "name": null,
          "structuredValue": 11877
        }
      ],
      "key": "id"
    },
    {
      "type": "string",
      "name": "label",
      "displayName": "label",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "Plaintext label for the taxon name comprised of both scientific name and authorship.\n",
      "examples": [
        {
          "value": "Jivarus Giglio-Tos, 1898",
          "strict": true,
          "name": null,
          "structuredValue": "Jivarus Giglio-Tos, 1898"
        }
      ],
      "key": "label"
    },
    {
      "type": "string",
      "name": "label_html",
      "displayName": "label_html",
      "typePropertyKind": "TYPE_EXPRESSION",
      "required": true,
      "description": "HTML-formatted label for the taxon name comprised of both scientific name and authorship.\n",
      "examples": [
        {
          "value": "<span class=\"klass\">\n  <i><mark>Jivarus</mark></i> Giglio-Tos, 1898</span>&nbsp;\n  <span class=\"feedback feedback-info feedback-thin\">genus</span>&nbsp;\n  <span class=\"feedback feedback-secondary feedback-thin\">Jivarini</span>&nbsp;\n  <span class=\"feedback feedback-notice feedback-thin\">Jivarus\n</span>\n",
          "strict": true,
          "name": null,
          "structuredValue": "<span class=\"klass\">\n  <i><mark>Jivarus</mark></i> Giglio-Tos, 1898</span>&nbsp;\n  <span class=\"feedback feedback-info feedback-thin\">genus</span>&nbsp;\n  <span class=\"feedback feedback-secondary feedback-thin\">Jivarini</span>&nbsp;\n  <span class=\"feedback feedback-notice feedback-thin\">Jivarus\n</span>\n"
        }
      ],
      "key": "label_html"
    }
  ]
}

/ New special parameters for model data requests

Apply to many model data requests: extend[] and embed[]
e.g., extend[]=citations will add any citation data to the response.
embed[]= adds a data attribute at the base of the response.
At this time, embed[] is available in asserted_distributions, biological_associations, citations, collecting_events, collection_objects, contents, data_attributes, identifiers, images, observation_matrices, observations, otus, people, sources, and taxon_names.

/

Base of the API. Includes an index of open projects indexed by project_token.

/ get

GET: /

Possible Responses

200

/ get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/"

RESPONSE BODY

Example

{
  "success": true,
  "open_projects": [
    {
      "mFPoRURskHhXu29nbAxoNy": "My TaxonWorks Project"
    }
  ]
}

Type: any

/ping

An open endpoint to test for life.

/ping get

GET: /ping

Possible Responses

200

/ping get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/ping"

RESPONSE BODY

Example

{
  "pong": true
}

Type: any

/user_authenticated

A single purpose route to test your User token.

/user_authenticated get

GET: /user_authenticated

Possible Responses

200

/user_authenticated get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/user_authenticated"

RESPONSE BODY

Example

{
  "success": true
}

Type: any

/project_authenticated

A single purpose route to test your Project token.

/project_authenticated get

GET: /project_authenticated

Query Parameters

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Possible Responses

200

/project_authenticated get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/project_authenticated?project_token=rIO2oWS603c5W5laQ8ornn"

RESPONSE BODY

Example

{
  "success": true,
  "open_projects": [
    {
      "mFPoRURskHhXu29nbAxoNy": "My TaxonWorks Project"
    }
  ]
}

Type: any

/both_authenticated

A single purpose route to test both User and Project tokens.

/both_authenticated get

GET: /both_authenticated

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Possible Responses

200

/both_authenticated get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/both_authenticated?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE BODY

Example

{
  "success": true
}

Type: any

/activity

See https://rdoc.taxonworks.org/Api/V1/StatsController.html

/activity get

GET: /activity

Get all activity, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_token

Security token for the project. Implicitly set project ID.

Property	Value
required	true
type	token

page

The page of activity result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of activity per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of activity per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of activity in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/activity get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/activity?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

{
  "data": {
    "Observations": 90,
    "Citation topics": 572737,
    "Citations": 2239039,
    "Notes": 373421,
    "Character states": 10,
    "Alternate values": 12805,
    "Data attributes": 13247699,
    "Tags": 390694,
    "Confidences": 267654,
    "Roles": 218801,
    "Sled images": 82,
    "Labels": 88,
    "Attributions": 163,
    "Dwc occurrences": 926081,
    "Sqed depictions": 121,
    "Depictions": 4719,
    "Documentation": 1987,
    "Documents": 1992,
    "Collection object observations": 2,
    "Pinboard items": 99,
    "Asserted distributions": 225045,
    "Biocuration classifications": 1129440,
    "Biological relationship types": 66,
    "Biological associations": 423693,
    "Biological relationships": 50,
    "Collection profiles": 21852,
    "Container items": 92656,
    "Containers": 45066,
    "Contents": 31,
    "Georeferences": 213476,
    "Identifiers": 2685855,
    "Loan items": 47436,
    "Loans": 3156,
    "Project sources": 271198,
    "Taxon determinations": 922489,
    "Type materials": 24381,
    "Collecting events": 270675,
    "Ranged lot categories": 1,
    "Images": 4265,
    "Common names": 823,
    "Taxon name classifications": 58513,
    "Taxon name relationships": 885852,
    "Controlled vocabulary terms": 2735,
    "Origin relationships": 79,
    "Sequences": 4,
    "Observation matrix columns": 25,
    "Observation matrix column items": 25,
    "Observation matrix rows": 11,
    "Observation matrix row items": 11,
    "Observation matrices": 14,
    "Collection objects": 926117,
    "Otus": 551396,
    "Taxon names": 754713,
    "Descriptors": 38,
    "Project members": 404,
    "Dataset record fields": 3266087,
    "Dataset records": 35799,
    "Import datasets": 8,
    "Sources": 324766,
    "Serials": 14864,
    "Organization": 1,
    "People": 205223,
    "GeographicArea": 34577,
    "Namespace": 83,
    "Preparation type": 8,
    "Repositories": 7032,
    "Projects": 138
  },
  "metadata": {
    "Days of curation": 14,
    "Past week: Active curators": 6,
    "Past week: New users": 3,
    "Past week: New sources": 0,
    "Past week: New taxon names": 1,
    "Past week: New collection objects": 0,
    "Past week: New collecting events": 0,
    "Past week: New observations": 56,
    "Past week: New citations": 0,
    "Past week: New images": 68,
    "Past week: New roles": 51,
    "Past week: New people": 0
  }
}

Type

array

/asserted_distributions

See Overview at http://rdoc.taxonworks.org/AssertedDistribution.html extend[]= available for [otu, geographic_area]

/asserted_distributions get

GET: /asserted_distributions

Get all asserted_distributions, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

asserted_distribution_id

ID for a specific asserted distribution type: integer required: false

Property	Value
required	true
type	string

asserted_distribution_id[]

IDs for specific asserted distributions

Property	Value
required	false
type	integer array

descendants

True: include descendants of taxon_name_id in scope, else type: boolean required: false

Property	Value
required	true
type	string

geo_json

Flag to return result as geoJSON

Property	Value
required	false
type	boolean

geographic_area_id

Identifier for the geographic area.

Property	Value
required	false
type	integer
examples	`33609`

geographic_area_id[]

Identifiers for specific geographic areas.

Property	Value
required	false
type	integer

geographic_area_mode

Flag to set area mode, in conjunction with geographic_area_id/geographic_area_id[] nil - non-spatial match by only those records matching the geographic_area_id exactly true - spatial match false - non-spatial match (descendants)

Property	Value
required	false
type	boolean, nil

otu_id

Identifier for the otu for which distribution is asserted.

Property	Value
required	false
type	integer

otu_id[]

Array of identifier IDs for otus for which distribution is asserted.

Property	Value
required	false
type	integer array

presence

true: return AssertedDistribution where the OTU is asserted as present according to the Sourcet; false: return data where the OTU is asserted as absent according to the Source; nil: not applied.

Property	Value
required	false
type	boolean

radius

Meters around shape boundary, 100m by default

Property	Value
required	false
type	integer

taxon_name_id

Return results for all OTUs corresponding to this taxon_name_id.

Property	Value
required	false
type	integer

taxon_name_id[]

Return results for all OTUs corresponding to these IDs.

Property	Value
required	false
type	integer array

wkt

WKT shape to search for asserted distributions

Property	Value
required	false
type	string

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

data_attribute_exact_value

Whether or not to match on exact value:

Property	Value
required	false
type	boolean

data_attribute_predicate_id

ID of controlled vocabulary term predicate.

Property	Value
required	false
type	integer

data_attribute_predicate_id[]

Array of IDs of controlled vocabulary term predicates.

Property	Value
required	false
type	integer

data_attribute_value

Value to match against.

Property	Value
required	false
type	string

data_attribute_value[]

Array of values to match against.

Property	Value
required	false
type	string

data_attributes

True: result has a data_attribute; False: does not have a data_attribute; nil: not applied.

Property	Value
required	false
type	boolean

identifier

Matches on cached

Property	Value
required	false
type	string

identifier_end

matches .identifier

Property	Value
required	false
type	string

identifier_exact

Match like or exact on cached

Property	Value
required	false
type	string

identifier_start

matches .identifier

Property	Value
required	false
type	string

identifier_type

Include Identifier data for a specific type, e.g, "Identifier::Local::CatalogNumber"

Property	Value
required	false
type	string

identifier_type[]

Include Identifier data for specific types.

Property	Value
required	false
type	string array

identifiers

true - has an identifier false - does not have an identifier nil - not applied

Property	Value
required	false
type	boolean

local_identifiers

true - has an local identifier false - does not have an local identifier

Property	Value
required	true
type	string

match_identifiers_delimiter

A list delimiter, defaults to ','. Is applied to match_identifiers to build an Array. Any reference is possible. '\t' is translated to "\t" '\n' is translated to "\n"

Property	Value
required	false
type	string

match_identifiers_type

one of 'internal' or 'identifier' if 'internal' then references the internal id of the object

Property	Value
required	false
type	string

namespace_id

The ID for the namespace name.

Property	Value
required	false
type	integer

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_and[]

List of keyword IDs for tags for this model instances where all enumerated keywords are present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or[]

List of keyword IDs for tags for this model instances where any of the enumerated keywords are present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of asserted_distributions result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of asserted_distributions per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of asserted_distributions per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of asserted_distributions in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/asserted_distributions get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/asserted_distributions?geographic_area_id=33609&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 1622,
    "otu_id": 2538,
    "geographic_area_id": 33666,
    "project_id": 2,
    "created_by_id": 1,
    "updated_by_id": 1,
    "is_absent": null,
    "created_at": "2022-12-24T21:02:14.022Z",
    "updated_at": "2022-12-24T21:02:14.022Z",
    "origin_citation_source_id": null,
    "global_id": "gid://taxon-works/AssertedDistribution/1622",
    "citations": [
      {
        "id": "669933",
        "global_id": "gid://taxon-works/Citation/669933",
        "pages": null,
        "source": {
          "name": "Blackith, R.E. (1992) In <i>Tetrigidae (Insecta; Orthoptera) of Southeast Asia: Annotated catalogue with partial translated keys and bibliography</i>. JAPAGA, Wicklow, Ireland. i-liv, 1–248.",
          "global_id": "gid://taxon-works/Source::Bibtex/3889"
        }
      }
    ],
    "otu": {
      "name": null,
      "taxon_name_id": 2580,
      "taxon_name": "Ergatettix dorsifer",
      "global_id": "gid://taxon-works/Otu/2538"
    },
    "geographic_area": {
      "id": 33666,
      "name": "China Southeast",
      "level0_id": null,
      "level1_id": null,
      "level2_id": null,
      "parent_id": 33569,
      "geographic_area_type_id": 111,
      "iso_3166_a2": null,
      "iso_3166_a3": null,
      "tdwgID": "36CHS",
      "data_origin": "tdwg_l3",
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2015-02-09T15:26:41.445Z",
      "updated_at": "2015-02-10T14:59:38.009Z",
      "geographic_area_type": {
        "id": 111,
        "name": "TDWG Level 3"
      },
      "parent": {
        "name": "China"
      }
    }
  },
  {
    "id": 1658,
    "otu_id": 2560,
    "geographic_area_id": 33666,
    "project_id": 2,
    "created_by_id": 1,
    "updated_by_id": 1,
    "is_absent": null,
    "created_at": "2022-12-24T21:02:18.719Z",
    "updated_at": "2022-12-24T21:02:18.719Z",
    "origin_citation_source_id": null,
    "global_id": "gid://taxon-works/AssertedDistribution/1658",
    "citations": [
      {
        "id": "670034",
        "global_id": "gid://taxon-works/Citation/670034",
        "pages": null,
        "source": {
          "name": "Blackith, R.E. (1992) In <i>Tetrigidae (Insecta; Orthoptera) of Southeast Asia: Annotated catalogue with partial translated keys and bibliography</i>. JAPAGA, Wicklow, Ireland. i-liv, 1–248.",
          "global_id": "gid://taxon-works/Source::Bibtex/3889"
        }
      }
    ],
    "otu": {
      "name": null,
      "taxon_name_id": 2601,
      "taxon_name": "Formosatettix robustus",
      "global_id": "gid://taxon-works/Otu/2560"
    },
    "geographic_area": {
      "id": 33666,
      "name": "China Southeast",
      "level0_id": null,
      "level1_id": null,
      "level2_id": null,
      "parent_id": 33569,
      "geographic_area_type_id": 111,
      "iso_3166_a2": null,
      "iso_3166_a3": null,
      "tdwgID": "36CHS",
      "data_origin": "tdwg_l3",
      "created_by_id": 1,
      "updated_by_id": 1,
      "created_at": "2015-02-09T15:26:41.445Z",
      "updated_at": "2015-02-10T14:59:38.009Z",
      "geographic_area_type": {
        "id": 111,
        "name": "TDWG Level 3"
      },
      "parent": {
        "name": "China"
      }
    }
  }
]

Type

array

/{id} get

GET: /asserted_distributions/{id}

Returns AssertedDistribution instance data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`4`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/asserted_distributions/{id}?project_id=4&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/biological_associations

See Overview at http://rdoc.taxonworks.org/BiologicalAssociation.html extend[]= available for [biological_relationship, subject, subject_biological_relationship_types, family_names, object, object_biological_relationship_types]

/biological_associations get

GET: /biological_associations

Get all biological_associations, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

biological_association_id

Search for a BiologicalAssociation by ID.

Property	Value
required	false
type	integer

biological_association_id[]

Search for BiologicalAssociations by IDs.

Property	Value
required	false
type	integer array

biological_associations_graph_id

Search by BiologicalAssociations graph ID for the associations.

Property	Value
required	false
type	integer

biological_associations_graph_id[]

Search by IDs of graphs for associations.

Property	Value
required	false
type	integer array

biological_relationship_id

Search for a BiologicalRelationship by ID.

Property	Value
required	false
type	integer

biological_relationship_id[]

Search for a BiologicalRelationships by IDs.

Property	Value
required	false
type	integer array

collecting_event_id

All BiologicalAssociations with CollectionObjects linked to a CollectingEvent.

Property	Value
required	false
type	integer

collecting_event_id[]

All BiologicalAssociations with CollectionObjects linked to one or more CollectingEvents.

Property	Value
required	false
type	integer array

collection_object_id

Find BiologicalRelationships with CollectionObject (only) matching subject OR object.

Property	Value
required	false
type	integer

collection_object_id[]

Search by collection object IDs.

Property	Value
required	false
type	integer array

descendants

True: include descendant OTUs.

Property	Value
required	false
type	boolean

exclude_taxon_name_relationship

True: return relationships excluding those linked by biological_relationship_id.

Property	Value
required	false
type	boolean

geo_json

Flag to return result as geoJSON

Property	Value
required	false
type	boolean

geographic_area_id

Identifier for the geographic area.

Property	Value
required	false
type	integer

geographic_area_id[]

Identifiers for specific geographic areas.

Property	Value
required	false
type	integer array

geographic_area_mode

Property	Value
required	false
type	boolean, nil

object_biological_property_id

Find all BiologicalAssociations with object having this property ID.

Property	Value
required	false
type	integer array

object_biological_property_id[]

Find all BiologicalAssociations with object having these property IDs.

Property	Value
required	false
type	integer array

object_object_global_id

Find all BiologicalAssociations with object having this global ID.

Property	Value
required	false
type	integer array

object_object_global_id[]

Find all BiologicalAssociations with object having these global IDs.

Property	Value
required	false
type	integer array

object_taxon_name_id

Find all BiologicalAssociations matching this (valid !) TaxonName or its children.

Property	Value
required	false
type	integer array

object_taxon_name_id[]

Find all BiologicalAssociations matching these (valid !) TaxonNames or their children.

Property	Value
required	false
type	integer array

object_type

Limit search to a specific subject type: Otu, CollectionObject; nil or not present means any.

Property	Value
required	false
type	string

otu_id

Find BiologicalAssociations with OTU (only) matching subject OR object.

Property	Value
required	false
type	integer array

otu_id[]

Array of OTU IDs for BiologicalAssociations with OTUs (only) matching subject OR object.

Property	Value
required	false
type	integer array

subject_biological_property_id

Find all BiologicalAssociations with subject having this property ID.

Property	Value
required	false
type	integer array

subject_biological_property_id[]

Find all BiologicalAssociations with subject having these property IDs.

Property	Value
required	false
type	integer array

subject_object_global_id

Find all BiologicalAssociations with subject having this global ID.

Property	Value
required	false
type	integer array

subject_object_global_id[]

Find all BiologicalAssociations with subject having these global IDs.

Property	Value
required	false
type	integer array

subject_taxon_name_id

Find all BiologicalAssociations matching this (valid !) TaxonName or its children.

Property	Value
required	false
type	integer

subject_taxon_name_id[]

Find all BiologicalAssociations matching these (valid !) TaxonNames or their children.

Property	Value
required	false
type	integer array

subject_type

Limit search to a specific subject type: Otu, CollectionObject; nil or not present means any.

Property	Value
required	false
type	string

taxon_name_id

Find all BiologicalAssociations matching this name or its children linked to this taxon_name_id.

Property	Value
required	false
type	integer

taxon_name_id[]

Find all BiologicalAssociations matching these names or their children linked to these taxon_name_id.

Property	Value
required	false
type	integer array

taxon_name_id_mode

Property	Value
required	true
type	string

wkt

WKT shape to search for biological associations.

Property	Value
required	false
type	string

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

identifier

Matches on cached

Property	Value
required	false
type	string

identifier_end

matches .identifier

Property	Value
required	false
type	string

identifier_exact

Match like or exact on cached

Property	Value
required	false
type	string

identifier_start

matches .identifier

Property	Value
required	false
type	string

identifier_type

Include Identifier data for a specific type, e.g, "Identifier::Local::CatalogNumber"

Property	Value
required	false
type	string

identifier_type[]

Include Identifier data for specific types.

Property	Value
required	false
type	string array

identifiers

true - has an identifier false - does not have an identifier nil - not applied

Property	Value
required	false
type	boolean

local_identifiers

true - has an local identifier false - does not have an local identifier

Property	Value
required	true
type	string

match_identifiers_delimiter

A list delimiter, defaults to ','. Is applied to match_identifiers to build an Array. Any reference is possible. '\t' is translated to "\t" '\n' is translated to "\n"

Property	Value
required	false
type	string

match_identifiers_type

one of 'internal' or 'identifier' if 'internal' then references the internal id of the object

Property	Value
required	false
type	string

namespace_id

The ID for the namespace name.

Property	Value
required	false
type	integer

note_exact

return Note if the exact text matches the note object.

Property	Value
required	false
type	boolean

note_text

Search for the exact text matching notes.

Property	Value
required	false
type	string

notes

True: only return objects with notes.

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_and[]

List of keyword IDs for tags for this model instances where all enumerated keywords are present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or[]

List of keyword IDs for tags for this model instances where any of the enumerated keywords are present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of biological_associations result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of biological_associations per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of biological_associations per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of biological_associations in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/biological_associations get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/biological_associations?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 1,
    "biological_relationship_id": 1,
    "biological_association_subject_id": 23068,
    "biological_association_subject_type": "Otu",
    "biological_association_object_id": 130025,
    "biological_association_object_type": "Otu",
    "created_by_id": 1623,
    "updated_by_id": 1623,
    "project_id": 2,
    "created_at": "2020-10-01T17:31:13.678Z",
    "updated_at": "2020-10-01T17:31:13.678Z",
    "object_tag": "<span class=\"otu_tag\"><span class=\"otu_tag_taxon_name\" title=\"23093\"><i>Gryllus</i> Linnaeus, 1758</span> &#10003;</span> <span class=\"notice\">predator / prey</span> <span class=\"otu_tag\"><span class=\"otu_tag_taxon_name\" title=\"174030\"><i>Plesiotettix sagittum</i> Silva & Cadena-Castañeda, 2020</span> &#10060;</span>",
    "object_label": null,
    "global_id": "gid://taxon-works/BiologicalAssociation/1",
    "base_class": "BiologicalAssociation",
    "url_for": "http://localhost:3000/api/v1/biological_associations",
    "object_url": "/biological_associations/1",
    "subject_global_id": "gid://taxon-works/Otu/23068",
    "object_global_id": "gid://taxon-works/Otu/130025",
    "biological_relationship": {
      "id": 1,
      "name": "predator",
      "inverted_name": "prey",
      "is_transitive": true,
      "is_reflexive": true,
      "created_by_id": 1623,
      "updated_by_id": 1623,
      "project_id": 2,
      "created_at": "2020-10-01T17:14:34.953Z",
      "updated_at": "2020-10-01T17:14:34.953Z",
      "object_tag": "predator / prey",
      "object_label": null,
      "global_id": "gid://taxon-works/BiologicalRelationship/1",
      "base_class": "BiologicalRelationship",
      "url_for": "http://localhost:3000/api/v1/biological_associations",
      "object_url": "/biological_relationships/1",
      "subject_biological_relationship_types": [],
      "object_biological_relationship_types": []
    },
    "citations": [],
    "subject": {
      "id": 23068,
      "name": null,
      "taxon_name_id": 23093,
      "created_by_id": 5,
      "updated_by_id": 5,
      "project_id": 2,
      "created_at": "2020-09-17T02:58:17.420Z",
      "updated_at": "2020-09-17T02:58:17.420Z",
      "object_tag": "<span class=\"otu_tag\"><span class=\"otu_tag_taxon_name\" title=\"23093\"><i>Gryllus</i> Linnaeus, 1758</span> &#10003;</span>",
      "object_label": "Gryllus Linnaeus, 1758",
      "global_id": "gid://taxon-works/Otu/23068",
      "base_class": "Otu",
      "url_for": "http://localhost:3000/api/v1/biological_associations",
      "object_url": "/otus/23068"
    },
    "object": {
      "id": 130025,
      "name": null,
      "taxon_name_id": 174030,
      "created_by_id": 1,
      "updated_by_id": 1,
      "project_id": 2,
      "created_at": "2020-09-28T19:00:18.147Z",
      "updated_at": "2020-09-28T19:00:18.147Z",
      "object_tag": "<span class=\"otu_tag\"><span class=\"otu_tag_taxon_name\" title=\"174030\"><i>Plesiotettix sagittum</i> Silva & Cadena-Castañeda, 2020</span> &#10060;</span>",
      "object_label": "Plesiotettix sagittum Silva & Cadena-Castañeda, 2020",
      "global_id": "gid://taxon-works/Otu/130025",
      "base_class": "Otu",
      "url_for": "http://localhost:3000/api/v1/biological_associations",
      "object_url": "/otus/130025"
    }
  }
]

Type

array

/{id} get

GET: /biological_associations/{id}

Returns BiologicalAssociations instance data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`2`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/biological_associations/{id}?project_id=2&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/citations

See Overview at http://rdoc.taxonworks.org/Citation.html extend[]= available for [citation_object, citation_topics, source, target_document]

/citations get

GET: /citations

Get all citations, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

citation_id

Find Citation by its ID.

Property	Value
required	false
type	integer

citation_id[]

Find Citations by their IDs.

Property	Value
required	false
type	integer

citation_object_id

Find by the ID for the object cited.

Property	Value
required	false
type	integer

citation_object_id[]

Find by the IDs for the objects cited.

Property	Value
required	false
type	integer

citation_object_type

Find with object type for the citation, such as TaxonDetermination, TaxonName, etc.

Property	Value
required	false
type	string

citation_object_type[]

Find with object types for the citations, such as TaxonDetermination, TaxonName, etc.

Property	Value
required	false
type	string

is_original

Find where the citation is the original description.

Property	Value
required	false
type	boolean

source_id

ID for the citation source.

Property	Value
required	false
type	integer

model_id

Get all the citations on the single object referenced by the parameter. E.g.: all citations on GET /otus/1. One of- asserted_distribution_id, biological_association_id, biological_associations_graph_id, biological_relationship_id, character_state_id, collecting_event_id, collection_object_id, common_name_id, confidence_id, content_id, data_attribute_id, descriptor_id, georeference_id, image_id, observation_id, observation_matrix_id, observation_matrix_row_id, observation_matrix_row_item_id, otu_id, protocol_id, taxon_determination_id, taxon_name_classification_id, taxon_name_id, taxon_name_relationship_id, type_material_id

Property	Value
required	false
type	integer

polymorphic

Property	Value
required	true
type	boolean

page

The page of citations result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of citations per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of citations per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of citations in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/citations get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/citations?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 786250,
    "citation_object_id": 17471,
    "citation_object_type": "AssertedDistribution",
    "source_id": 16340,
    "pages": null,
    "is_original": null,
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 4,
    "citation_source_body": "Alfken, 1901"
  },
  {
    "id": 59553,
    "citation_object_id": 60145,
    "citation_object_type": "TaxonName",
    "source_id": 16340,
    "pages": "142",
    "is_original": true,
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 4,
    "citation_source_body": "Alfken, 1901:142"
  },
  {
    "id": 785075,
    "citation_object_id": 16319,
    "citation_object_type": "AssertedDistribution",
    "source_id": 17136,
    "pages": null,
    "is_original": null,
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 4,
    "citation_source_body": "Andersen & Kjaerandsen, 1995"
  }
]

Type

array

/{id} get

GET: /citations/{id}

Returns Citations instance data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`4`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/citations/{id}?project_id=4&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/collecting_events

See Overview at http://rdoc.taxonworks.org/CollectingEvent.html extend[]= available for [parent, roles]

/collecting_events get

GET: /collecting_events

Get all collecting_events, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

collecting_events_wildcards[]

ATTRIBUTES that can be wildcarded. See https://www.rubydoc.info/github/SpeciesFileGroup/taxonworks/CollectingEvent, Instance Attribute Summary, which details columns of the collecting_events table.

Property	Value
required	false
type	string array

collection_objects

true: match only CollectingEvents with associated CollectionObjects false: match only CollectingEvents without associated CollectionObjects nil: not applied

Property	Value
required	false
type	boolean

collector_id

A single collector ID

Property	Value
required	false
type	integer

collector_id[]

List of collector IDs

Property	Value
required	false
type	integer array

collector_id_or

Find collecting events with ANY one of these collectors (true) or ALL of these collectors (false/nil)

Property	Value
required	false
type	boolean

collector_id_or[]

Find collecting events with ANY of these collectors (true) or ALL of these collectors (false/nil)

Property	Value
required	false
type	boolean

collectors

Find collecting events when true: a collector role exists, false: a collector role doesn't exist, nil: not applied.

Property	Value
required	false
type	boolean

end_date

Find CollectingEvents with this end date or earlier.

Property	Value
required	false
type	string

geo_json

geoJSON of the search area

Property	Value
required	false
type	string

geographic_area

true: where CollectingEvent has geographic_area; false: where not geographic_area; nil: not applied.

Property	Value
required	false
type	integer

geographic_area_id

Single geographic area ID for search

Property	Value
required	false
type	integer

geographic_area_id[]

List of geographic area IDs for search

Property	Value
required	false
type	integer

geographic_area_mode

Property	Value
required	false
type	boolean, nil

georeferences

true: where CollectingEvent has georeferences; false: where not georeferenced; nil: not applied.

Property	Value
required	true
type	boolean

in_labels

Wildcard wrapped match against any label

Property	Value
required	false
type	string

in_verbatim_locality

Wildcard wrapped match against verbatim locality (via ATTRIBUTES)

Property	Value
required	false
type	string

keyword_id_and[]

List of keyword IDs for associated collecting events where all enumerated keywords are present.

Property	Value
required	false
type	integer array

keyword_id_or[]

List of keyword IDs for associated collecting events where any of the enumerated keywords are present.

Property	Value
required	false
type	integer array

otu_ids

A single OTU ID to match.

Property	Value
required	false
type	string integer

otu_id[]

List of OTU IDs to all match.

Property	Value
required	false
type	integer array

md5_verbatim_labels

Property	Value
required	true
type	Include metadata for verbatim labels.

radius

Search area radius in meters.

Property	Value
required	false
type	integer

recent

Property	Value
required	true
type	string

start_date

Find CollectingEvents with this start date or later.

Property	Value
required	false
type	string

use_max

The maximum number of CollectionObjects linked to CollectingEvent.

Property	Value
required	true
type	string

use_min

The minimum number of CollectionObjects linked to CollectingEvent.

Property	Value
required	true
type	string

wkt

Well Known Text describing the search area.

Property	Value
required	false
type	string

_optional_parameters

meta_prioritize_geographic_area, min_ma, max_ma, lithology, member, formation, group, end_date_month, start_date_month, verbatim_date, time_end_second, time_end_minute, time_end_hour, time_start_second, time_start_minute, time_start_hour, verbatim_datum, verbatim_elevation, verbatim_habitat, end_date_day, start_date_day, end_date_year, start_date_year, md5_of_verbatim_label, field_notes, elevation_precision, maximum_elevation, minimum_elevation, verbatim_method, verbatim_collectors, verbatim_trip_identifier, verbatim_geolocation_uncertainty, verbatim_latitude, verbatim_longitude, verbatim_locality, document_label, print_label, verbatim_label

Property	Value
required	false
type	string

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

data_attribute_exact_value

Whether or not to match on exact value:

Property	Value
required	false
type	boolean

data_attribute_predicate_id

ID of controlled vocabulary term predicate.

Property	Value
required	false
type	integer

data_attribute_predicate_id[]

Array of IDs of controlled vocabulary term predicates.

Property	Value
required	false
type	integer

data_attribute_value

Value to match against.

Property	Value
required	false
type	string

data_attribute_value[]

Array of values to match against.

Property	Value
required	false
type	string

data_attributes

True: result has a data_attribute; False: does not have a data_attribute; nil: not applied.

Property	Value
required	false
type	boolean

image_id

ID for the image object to be found.

Property	Value
required	false
type	integer

image_id[]

Array of IDs for the image objects to be found.

Property	Value
required	false
type	integer

images

true: has images false: doesn't have images

Property	Value
required	false
type	boolean

identifier

Matches on cached

Property	Value
required	false
type	string

identifier_end

matches .identifier

Property	Value
required	false
type	string

identifier_exact

Match like or exact on cached

Property	Value
required	false
type	string

identifier_start

matches .identifier

Property	Value
required	false
type	string

identifier_type

Include Identifier data for a specific type, e.g, "Identifier::Local::CatalogNumber"

Property	Value
required	false
type	string

identifier_type[]

Include Identifier data for specific types.

Property	Value
required	false
type	string array

identifiers

true - has an identifier false - does not have an identifier nil - not applied

Property	Value
required	false
type	boolean

local_identifiers

true - has an local identifier false - does not have an local identifier

Property	Value
required	true
type	string

match_identifiers_delimiter

A list delimiter, defaults to ','. Is applied to match_identifiers to build an Array. Any reference is possible. '\t' is translated to "\t" '\n' is translated to "\n"

Property	Value
required	false
type	string

match_identifiers_type

one of 'internal' or 'identifier' if 'internal' then references the internal id of the object

Property	Value
required	false
type	string

namespace_id

The ID for the namespace name.

Property	Value
required	false
type	integer

note_exact

return Note if the exact text matches the note object.

Property	Value
required	false
type	boolean

note_text

Search for the exact text matching notes.

Property	Value
required	false
type	string

notes

True: only return objects with notes.

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of collecting_events result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of collecting_events per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of collecting_events per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of collecting_events in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/collecting_events get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/collecting_events?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 9822,
    "verbatim_label": null,
    "print_label": null,
    "document_label": null,
    "verbatim_locality": "Kunashir Island, environs of village Alekhino",
    "verbatim_longitude": "145.528",
    "verbatim_latitude": "43.9191",
    "verbatim_geolocation_uncertainty": null,
    "verbatim_trip_identifier": null,
    "verbatim_collectors": "A. Gorochov",
    "verbatim_method": null,
    "verbatim_elevation": null,
    "verbatim_habitat": null,
    "verbatim_datum": null,
    "verbatim_date": null,
    "geographic_area_id": 33786,
    "minimum_elevation": null,
    "maximum_elevation": null,
    "elevation_precision": null,
    "start_date_day": null,
    "start_date_month": null,
    "start_date_year": null,
    "end_date_day": null,
    "end_date_month": null,
    "end_date_year": null,
    "time_start_hour": null,
    "time_start_minute": null,
    "time_start_second": null,
    "time_end_hour": null,
    "time_end_minute": null,
    "time_end_second": null,
    "field_notes": null,
    "md5_of_verbatim_label": null,
    "min_ma": null,
    "max_ma": null,
    "cached": null,
    "cached_level0_geographic_name": null,
    "cached_level1_geographic_name": null,
    "cached_level2_geographic_name": null,
    "group": null,
    "formation": null,
    "member": null,
    "lithology": null,
    "identifiers": [],
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "created_at": "2021-08-14T20:11:19.985Z",
    "updated_at": "2021-08-14T20:11:19.985Z",
    "global_id": "gid://taxon-works/CollectingEvent/9822"
  },
  {
    "id": 9823,
    "verbatim_label": null,
    "print_label": null,
    "document_label": null,
    "verbatim_locality": "Kunashir Island, Tyatya volcano",
    "verbatim_longitude": "146.256519",
    "verbatim_latitude": "44.360256",
    "verbatim_geolocation_uncertainty": null,
    "verbatim_trip_identifier": null,
    "verbatim_collectors": null,
    "verbatim_method": null,
    "verbatim_elevation": null,
    "verbatim_habitat": null,
    "verbatim_datum": null,
    "verbatim_date": null,
    "geographic_area_id": 33786,
    "minimum_elevation": null,
    "maximum_elevation": null,
    "elevation_precision": null,
    "start_date_day": null,
    "start_date_month": null,
    "start_date_year": null,
    "end_date_day": null,
    "end_date_month": null,
    "end_date_year": null,
    "time_start_hour": null,
    "time_start_minute": null,
    "time_start_second": null,
    "time_end_hour": null,
    "time_end_minute": null,
    "time_end_second": null,
    "field_notes": null,
    "md5_of_verbatim_label": null,
    "min_ma": null,
    "max_ma": null,
    "cached": null,
    "cached_level0_geographic_name": "Russia",
    "cached_level1_geographic_name": "Sakhalin",
    "cached_level2_geographic_name": null,
    "group": null,
    "formation": null,
    "member": null,
    "lithology": null,
    "identifiers": [],
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "created_at": "2021-08-14T20:11:20.786Z",
    "updated_at": "2021-08-14T20:11:20.786Z",
    "global_id": "gid://taxon-works/CollectingEvent/9823"
  }
]

Type

array

/collection_objects

See Overview at http://rdoc.taxonworks.org/CollectionObject.html Extend[]= available for [container, dwc_fields, type_material, taxon_determination_images]

/collection_objects get

GET: /collection_objects

Get all collection_objects, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

biocuration_class_id

Include results for biocuration classes for this ID.

Property	Value
required	false
type	integer

biocuration_class_id[]

Include results for biocuration classes for these IDs.

Property	Value
required	false
type	integer

biological_association_id

Include results for biological associations for this ID.

Property	Value
required	false
type	integer

biological_association_id[]

Include results for biological associations for these IDs.

Property	Value
required	false
type	integer

biological_associations

true: get collecting event that has BiologicalAssociation ?!? false - get collecting event that does not have BiologicalAssociation nil: not applied.

Property	Value
required	false
type	boolean

biological_relationship_id

Include results for biological relationships for this ID.

Property	Value
required	false
type	integer

biological_relationship_id[]

Include results for biological relationships for these IDs.

Property	Value
required	false
type	integer

buffered_collecting_event

Include data where collecting event information contains this text value.

Property	Value
required	false
type	string

buffered_determinations

Include data where determination contains this text value.

Property	Value
required	false
type	string

buffered_other_labels

Include data where other labels information contains this text value.

Property	Value
required	false
type	string

collecting_event

true: return CollectionObject if there is an associated collecting event (has a collecting_event_id); false: return CollectionObject if it has no collecting_event_id; nil: not applied.

Property	Value
required	false
type	boolean

collecting_event_id

only return CollectingObject with this collecting event ID.

Property	Value
required	false
type	integer array

collecting_event_id[]

only return CollectingObjects with these collecting event IDs.

Property	Value
required	false
type	integer array

collection_object_id

return CollectingObject with this ID.

Property	Value
required	false
type	integer

collection_object_id[]

return CollectingObjects with these IDs.

Property	Value
required	false
type	integer array

collection_object_type

Type of collection object, e.g., "Specimen".

Property	Value
required	false
type	string
oneOf	Lot, RangedLot, Specimen

collectors

true: a collector role exists; false: no collector role exists; nil - not applied

Property	Value
required	false
type	boolean

current_determinations

true: TaxonDetermination must be .current; false: TaxonDetermination must be .historical. nil: TaxonDeterminations match regardless of current or historical

Property	Value
required	false
type	boolean

current_repository

true: has current_repository_id; false: does not have current_repository_id; nil: not applied.

Property	Value
required	false
type	boolean

current_repository_id

Find collection_objects in this repository by this ID.

Property	Value
required	false
type	integer

current_repository_id[]

Find collection_objects in these repositories by these IDs.

Property	Value
required	false
type	integer array

descendants

true: provide collection objects for OTU descendants linked to TaxonNameIDs false: do not return descendant data. See also taxon_name_id. nil: ignored

Property	Value
required	false
type	boolean

dates

true: any of start/end date or verbatim date are populated false: none of start/end date or verbatim date are populated nil: ignored

Property	Value
required	false
type	boolean

determiner_id

Include results which are related to this determiner (person by ID),

Property	Value
required	true
type	integer

determiner_id[]

Include results which are related to any of these determiners (people by IDs), e.g., determiner_id[]=325&determiner_id[]=9032

Property	Value
required	false
type	integer array

determiner_id_or

true: treat iIDs as "and" (only collection objects with all and only all will match) false or nil: treat Ids as "or".

Property	Value
required	true
type	string

determiners

true: a determiner role exists; false: no determiner role exists. nil: not applied.

Property	Value
required	false
type	boolean

dwc_indexed

Include metadata for Darwin Core indexed objects; true / false index is/not built, if not present ignore.

Property	Value
required	false
type	boolean

end_date

Limit search to dates prior to this value.

Property	Value
required	false
type	string

exact_buffered_collecting_event

Include data where collecting event information contains this exact text value.

Property	Value
required	false
type	string

exact_buffered_determinations

Include data where determinations information contains this exact text value.

Property	Value
required	false
type	string

exact_buffered_other_labels

Include data where other labels information contains this exact text value.

Property	Value
required	false
type	string

extract_id

match all CollectionObjects that are the origin of this Extract.

Property	Value
required	false
type	integer

extract_id[]

match all CollectionObjects that are the origin of these Extracts.

Property	Value
required	false
type	integer

geo_json

geoJSON of the search area.

Property	Value
required	false
type	string

geographic_area

Find if associated collecting event has/not a geographic area. Ignored if param not present.

Property	Value
required	false
type	boolean

geographic_area_ids[]

List of IDs for associated geographic areas.

Property	Value
required	false
type	integer

georeferences

true: collecting event has one ore more georeferences; false: does not have any georeferences; nil: not applied.

Property	Value
required	false
type	boolean

identifier

Identifier associated with collection object.

Property	Value
required	false
type	string

identifier_end

Last part of identifier associated with collection object

Property	Value
required	false
type	string

identifier_exact

Exact identifier associated with collection object

Property	Value
required	false
type	string

identifier_start

First part of identifier associated with collection object

Property	Value
required	false
type	string

identifiers

Include metadata for associated collecting event identifiers.

Property	Value
required	false
type	boolean

in_labels

Search wildcard in all related collecting event labels.

Property	Value
required	false
type	boolean

in_verbatim_locality

Search in verbatim locality in related collecting events.

Property	Value
required	false
type	boolean

is_type[]

Include metadata for primary types by IDs

Property	Value
required	false
type	integer array

keyword_id_and[]

Search must include all keyword IDs

Property	Value
required	false
type	string integer

keyword_id_or[]

Search may include any of these keyword IDs

Property	Value
required	false
type	string integer

loaned

true: the CollectionObject has been loaned at least once, false - is not now loaned; nil: not applied

Property	Value
required	false
type	boolean

md5_verbatim_label

Match md5 verbatim label if in_labels is true

Property	Value
required	false
type	string

namespace_id

Include metadata for associated identifier namespace by id.

Property	Value
required	false
type	integer

never_loaned

true: Return data for CollectionObjects never loaned.

Property	Value
required	false
type	boolean

on_loan

true: the CollectionObject currently on loan.

Property	Value
required	false
type	boolean

otu_ids[]

Filter by OTU IDs.

Property	Value
required	false
type	integer

partial_overlap_dates

Allow date overlap.

Property	Value
required	false
type	boolean

preparation_type

true: has preparation_type; false: does not have preparation_type; nil: not applied.

Property	Value
required	false
type	boolean

preparation_type_id

The ID for a single preparation type in the search.

Property	Value
required	false
type	integer

preparation_type_id[]

The IDs for preparation types in the search.

Property	Value
required	false
type	integer array

radius

Radius around location

Property	Value
required	false
type	string

repository

true: has repository_id; false: does not have repository_id; nil: not applied.

Property	Value
required	false
type	integer

repository_id

return CollectionObjects for repository by id.

Property	Value
required	false
type	integer

sled_image_id

return CollectionObjects for SLED images by id.

Property	Value
required	false
type	integer

start_date

Limit search to dates later

Property	Value
required	false
type	string

taxon_determination_id

Include taxon determinations.

Property	Value
required	false
type	boolean

taxon_determinations

[object Object]

Property	Value
required	false
type	boolean

taxon_name_id

return collection objects associated with OTUs associated with this taxon name by its ID.

Property	Value
required	false
type	integer

taxon_name_id[]

return collection objects associated with OTUs associated with these taxon name by their ID.

Property	Value
required	false
type	integer

type_material

Property	Value
required	false
type	boolean

type_specimen_taxon_name_id

Include data for specific type taxon by id.

Property	Value
required	false
type	integer

user_date_end

Limit search to user dates prior.

Property	Value
required	false
type	string

user_date_start

Limit search to user dates later.

Property	Value
required	false
type	string

user_id

ID of the user for date ranges.

Property	Value
required	false
type	string integer

user_target

One of "created" or "updated"; if absent, both are searched.

Property	Value
required	false
type	string

validity

true: match against only valid ancestors; false: match against only invalid ancestors; nil: not applied.

Property	Value
required	false
type	boolean

with_buffered_collecting_event

true: return collection objects with buffered collecting event field value. false | nil: return collection objects without buffered collecting event field value.

Property	Value
required	false
type	boolean

with_buffered_determinations

true: return collection objects with buffered determination field value. false | nil: return collection objects without buffered determination field value.

Property	Value
required	false
type	boolean

with_buffered_other_labels

true: return collection objects with buffered other labels field value. false | nil: return collection objects without buffered other labels field value.

Property	Value
required	false
type	boolean

wkt

Well Known Text describing the search area.

Property	Value
required	false
type	string

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

image_id

ID for the image object to be found.

Property	Value
required	false
type	integer

image_id[]

Array of IDs for the image objects to be found.

Property	Value
required	false
type	integer

images

true: has images false: doesn't have images

Property	Value
required	false
type	boolean

note_exact

return Note if the exact text matches the note object.

Property	Value
required	false
type	boolean

note_text

Search for the exact text matching notes.

Property	Value
required	false
type	string

notes

True: only return objects with notes.

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of collection_objects result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of collection_objects per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of collection_objects per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of collection_objects in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/collection_objects get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/collection_objects?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 89244,
    "total": 1,
    "preparation_type_id": null,
    "collecting_event_id": 59484,
    "repository_id": 197,
    "type": "Specimen",
    "buffered_collecting_event": "“Mohave Co. AZ, Colorado R. GC, rm211.5R, 4/13/02, Coll. R.J.Delph, Ex: Light, Old High Water, blue label with ‘3’,” “HOLOTYPE Arenivaga grandiscanyonensis Hopkins, 2012” [red label with black border].",
    "buffered_determinations": null,
    "buffered_other_labels": null,
    "ranged_lot_category_id": null,
    "accessioned_at": null,
    "deaccessioned_at": null,
    "deaccession_reason": null,
    "created_by_id": 908,
    "updated_by_id": 908,
    "project_id": 4,
    "created_at": "2015-01-19T09:15:00.000Z",
    "updated_at": "2015-01-19T14:07:00.000Z",
    "global_id": "gid://taxon-works/Specimen/89244",
    "contained_in": null
  },
  {
    "id": 90233,
    "total": 1,
    "preparation_type_id": null,
    "collecting_event_id": 59485,
    "repository_id": 197,
    "type": "Specimen",
    "buffered_collecting_event": "“Mohave Co. AZ, Colorado R. GC, blue label with ‘3’, rm202.5L, 9/4/03, Coll. R.J.Delph, Ex: Light, New High Water” “HOLOTYPE Arenivaga pagana Hopkins, 2012”",
    "buffered_determinations": null,
    "buffered_other_labels": null,
    "ranged_lot_category_id": null,
    "accessioned_at": null,
    "deaccessioned_at": null,
    "deaccession_reason": null,
    "created_by_id": 908,
    "updated_by_id": 908,
    "project_id": 4,
    "created_at": "2015-03-08T09:22:00.000Z",
    "updated_at": "2015-03-08T09:24:00.000Z",
    "global_id": "gid://taxon-works/Specimen/90233",
    "contained_in": null
  }
]

Type

array

/{id} get

GET: /collection_objects/{id}

Returns collection objects data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/collection_objects/{id}?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/{id}/dwc get

GET: /collection_objects/{id}/dwc

Get DWC formatted data for collecton object with ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id}/dwc get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/collection_objects/{id}/dwc?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/contents

See Overview at http://rdoc.taxonworks.org/Content.html extend[]= available for [public_content, otu, topic]

/contents get

GET: /contents

Get all contents, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

exact

Return string in the content should match exactly.

Property	Value
required	false
type	boolean

otu_id

ID of an OTU to be included in the search.

Property	Value
required	false
type	integer

otu_id[]

IDs of OTUs to be included in the search.

Property	Value
required	false
type	integer array

text

Text segment to be searched for in contents.

Property	Value
required	false
type	string
examples	`subterr`

topic_id

ID of a topic to be included in the search.

Property	Value
required	false
type	integer

topic_id[]

IDs of topics to be included in the search.

Property	Value
required	false
type	integer array

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

image_id

ID for the image object to be found.

Property	Value
required	false
type	integer

image_id[]

Array of IDs for the image objects to be found.

Property	Value
required	false
type	integer

images

true: has images false: doesn't have images

Property	Value
required	false
type	boolean

page

The page of contents result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of contents per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of contents per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of contents in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/contents get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/contents?text=subterr&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 172,
    "text": "* Life zone [terrestrial]: Omnivorous; entirely subterranean.",
    "otu_id": 171,
    "topic_id": 1,
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "revision_id": null,
    "created_at": "2020-09-17T02:19:57.752Z",
    "updated_at": "2020-09-17T02:19:57.752Z",
    "global_id": "gid://taxon-works/Content/172",
    "otu": {
      "global_id": "gid://taxon-works/Otu/171"
    },
    "topic": {
      "global_id": "gid://taxon-works/Topic/1",
      "uri": null
    }
  },
  {
    "id": 30912,
    "text": "* Life zone [terrestrial]: Carnivorous and omnivorous, entirely subterranean.",
    "otu_id": 30828,
    "topic_id": 1,
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "revision_id": null,
    "created_at": "2020-09-17T03:11:21.875Z",
    "updated_at": "2020-09-17T03:11:21.875Z",
    "global_id": "gid://taxon-works/Content/30912",
    "otu": {
      "global_id": "gid://taxon-works/Otu/30828"
    },
    "topic": {
      "global_id": "gid://taxon-works/Topic/1",
      "uri": null
    }
  }
]

Type

array

/{id} get

GET: /contents/{id}

Returns Content instance data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`2`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/contents/{id}?project_id=2&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/data_attributes

See Overview at http://rdoc.taxonworks.org/Data_attribute.html

/depictions

See Overview at http://rdoc.taxonworks.org/Depiction.html

/depictions get

GET: /depictions

Get all depictions, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/depictions get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/depictions?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/downloads

See Overview at http://rdoc.taxonworks.org/Download.html

/downloads get

GET: /downloads

Get all downloads, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/downloads get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/downloads?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/{id} get

GET: /downloads/{id}

Returns Download metadata instance

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`1`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/downloads/{id}?project_id=1&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/{id}/{file} get

GET: /downloads/{id}/{file}

Downloads metadata instance to specified file path

URI Parameters

Property	Value
required	true
type	string

file

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id}/{file} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/downloads/{id}/{file}?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/dwc_occurrences

See Overview at https://rdoc.taxonworks.org/DwcOccurrence.html

/dwc_occurrences get

GET: /dwc_occurrences

Get all dwc_occurrences, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

dwc_occurrence_id

ID of Occurrance

Property	Value
required	false
type	integer

dwc_occurrence_id[]

Array of IDs of Occurrances

Property	Value
required	false
type	integer array

dwc_occurrence_object_id

ID of Occurrances object

Property	Value
required	false
type	integer

dwc_occurrence_object_id[]

Array of IDs of Occurrances object IDs

Property	Value
required	false
type	integer array

dwc_occurrence_object_type

Single ID of Occurrances object types

Property	Value
required	false
type	integer

dwc_occurrence_object_type[]

Array of IDs of Occurrances object types

Property	Value
required	false
type	integer array

page

The page of dwc_occurrences result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of dwc_occurrences per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of dwc_occurrences per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of dwc_occurrences in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/dwc_occurrences get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/dwc_occurrences?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 1,
    "basisOfRecord": "PreservedSpecimen",
    "country": "Madagascar",
    "family": "Gryllidae",
    "genus": "Gialaia",
    "individualCount": 1,
    "kingdom": "Animalia",
    "nomenclaturalCode": "iczn",
    "occurrenceID": "68086f02-23d8-4bc4-b7da-c99f6a18df3a",
    "occurrenceStatus": "present",
    "scientificName": "Gialaia (Gialaia) africana Gorochov & Kostia, 1999",
    "scientificNameAuthorship": "Gorochov & Kostia, 1999",
    "specificEpithet": "africana",
    "taxonRank": "species",
    "typeStatus": "syntype of Gialaia africana Gorochov & Kostia, 1999",
    "dwc_occurrence_object_type": "CollectionObject",
    "dwc_occurrence_object_id": 10,
    "project_id": 2,
    "created_at": "2022-12-25T00:00:26.012Z",
    "updated_at": "2022-12-25T00:00:23.407Z"
  }
]

Type

array

/extracts

See Overview at https://rdoc.taxonworks.org/Extract.html

/extracts get

GET: /extracts

Get all extracts, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

collection_object_id

Return results for this collection object ID.

Property	Value
required	false
type	integer

collection_object_id[]

Return results for these collection object IDs.

Property	Value
required	false
type	integer

descendants

Return all extracts linked to OTUs AND CollectionObject that is self or descendant linked

Property	Value
required	false
type	boolean

exact_verbatim_anatomical_origin

Return result if true: has this exact anatomical origin; false:does not have this origin; nil: disregard.

Property	Value
required	false
type	boolean

extract_end_date_range

A date in the format yyyy-mm-dd.

Property	Value
required	false
type	datetime

extract_id

Return results for this extract ID.

Property	Value
required	false
type	integer

extract_id[]

Return results for these extract IDs.

Property	Value
required	false
type	integer array

extract_origin

One of: 'Extract', 'Specimen', 'Lot', 'RangedLot', 'Otu', 'CollectionObject'

Property	Value
required	false
type	string

extract_start_date_range

A date in the format yyyy-mm-dd.

Property	Value
required	false
type	datetime

otu_id

Return results for this OTU ID.

Property	Value
required	false
type	integer

otu_id[]

Return results for these OTU IDs.

Property	Value
required	false
type	integer array

protocol_id

Return results for this protocol ID.

Property	Value
required	false
type	integer

repository_id

Return results for this repository ID.

Property	Value
required	false
type	integer

repository_id[]

Return results for these repository IDs.

Property	Value
required	false
type	integer array

sequences

Include results with sequences.

Property	Value
required	false
type	boolean

taxon_name_id

Return all extracts linked to OTUs AND CollectionObject that is self or descendant linked

Property	Value
required	false
type	integer

taxon_name_id[]

Return all extracts linked to OTUs AND CollectionObject that is self or descendant linked

Property	Value
required	false
type	integer array

verbatim_anatomical_origin

Return result for this anatomical origin.

Property	Value
required	false
type	string

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_and[]

List of keyword IDs for tags for this model instances where all enumerated keywords are present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or[]

List of keyword IDs for tags for this model instances where any of the enumerated keywords are present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of extracts result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of extracts per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of extracts per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of extracts in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/extracts get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/extracts?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[]

Type

array

/identifers

See Overview at http://rdoc.taxonworks.org/Identifier.html extend[]= available for [namespace]

/identifers get

GET: /identifers

Get all identifers, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

identifier

Search for this string.

Property	Value
required	false
type	string

identifier[]

Search for these strings.

Property	Value
required	false
type	string array

identifier_id

Return identifier with this ID.

Property	Value
required	false
type	integer

identifier_id[]

Return identifiers with these IDs.

Property	Value
required	false
type	integer array

identifier_object_id

Return identifier for an ID of an object.

Property	Value
required	false
type	integer

identifier_object_id[]

Return identifiers for an array of IDs of objects identifier_object_id[]=47&identifier_object_id[]=2232.

Property	Value
required	false
type	integer array

identifier_object_type

Return identifier for an object type, case sensitive.

Property	Value
required	false
type	string

identifier_object_type[]

Return identifiers for an array of object types. ?identifier_object_type[]=CollectionObject&identifier_object_type[]=Serial

Property	Value
required	false
type	string array

namespace_id

Return identifier with this ID for the namespace.

Property	Value
required	false
type	integer

namespace_id[]

Return identifier with these IDs for namespaces.

Property	Value
required	false
type	integer

namespace_name

The namespace name for the identifier.

Property	Value
required	false
type	string

namespace_short_name

The short version of the namespace name for the identifier.

Property	Value
required	false
type	string

object_global_id

Filter by object global ID

Property	Value
required	false
type	integer

query_string

A fully qualified identifier, matches cached. !! This is the only wildcarded value !!

Property	Value
required	false
type	string

type

Return identifier(s) for a specific type, e.g, "Identifier::Local::CatalogNumber"

Property	Value
required	false
type	string

polymorphic

Property	Value
required	true
type	boolean

page

The page of identifers result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of identifers per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of identifers per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of identifers in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/identifers get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/identifers?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 142827,
    "identifier_object_id": 38,
    "identifier_object_type": "CollectionObject",
    "identifier": "10463",
    "type": "Identifier::Local::CatalogNumber",
    "cached": "NHMUK 10463",
    "namespace_id": 37,
    "created_by_id": 1,
    "updated_by_id": 1,
    "identifier_object_global_id": "gid://taxon-works/Specimen/38"
  },
  {
    "id": 142828,
    "identifier_object_id": 196,
    "identifier_object_type": "CollectionObject",
    "identifier": "AMNZ21862",
    "type": "Identifier::Local::CatalogNumber",
    "cached": "AIM AMNZ21862",
    "namespace_id": 412,
    "created_by_id": 1,
    "updated_by_id": 1,
    "identifier_object_global_id": "gid://taxon-works/Specimen/196"
  },
  {
    "id": 142829,
    "identifier_object_id": 914,
    "identifier_object_type": "CollectionObject",
    "identifier": "8819",
    "type": "Identifier::Local::CatalogNumber",
    "cached": "NMW 8819",
    "namespace_id": 496,
    "created_by_id": 1,
    "updated_by_id": 1,
    "identifier_object_global_id": "gid://taxon-works/Specimen/914"
  }
]

Type

array

/images

See Overview at http://rdoc.taxonworks.org/Observation.html extend[]= available for [depictions, attribution, source]

/images get

GET: /images

Get all images, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

biocuration_class_id

Include metadata for biocuration classes by id

Property	Value
required	false
type	string integer

biocuration_class_id[]

Include metadata for biocuration classes by id array

Property	Value
required	false
type	integer array

collection_object_id

Identifier associated with collection object

Property	Value
required	false
type	string integer

collection_object_id[]

Identifier associated with collection object

Property	Value
required	false
type	integer array

collection_object_scope

Return Images associated with one or more of below:

Property	Value
required	false
type	string
oneOf	[object Object], :collection_objects, :observations, :collecting_events

depictions

Return image(s) true: imahe is used in a depiction; false: not used; nil: not applied.

Property	Value
required	false
type	boolean

depiction_object_type

Restricts Images to those that depict one or more names of classes.

Property	Value
required	false
type	string

image_id

ID for the image

Property	Value
required	false
type	string integer
examples	`1`

image_id[]

List of IDs for images e.g., image_id[]=34&image_id[]=398&image_id[]=726

Property	Value
required	false
type	integer array

otu_id

ID for a specific OTU

Property	Value
required	false
type	string integer

otu_id[]

List of OTU IDs e.g., otu_id[]=768&otu_id[]=1024&otu_id[]=2047

Property	Value
required	false
type	integer array

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_and[]

List of keyword IDs for tags for this model instances where all enumerated keywords are present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or[]

List of keyword IDs for tags for this model instances where any of the enumerated keywords are present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of images result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of images per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of images per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of images in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/images get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/images?image_id=1&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

{
  "id": 1,
  "height": 721,
  "width": 766,
  "image_file_fingerprint": "a7b370c43fb3a976cdc53c3d6f57be71",
  "image_file_file_name": "126710",
  "image_file_file_size": 674248,
  "created_by_id": 5,
  "updated_by_id": 5,
  "pixels_to_centimeter": null,
  "original": "http://localhost:3000/s/dk07y4",
  "thumb": "http://localhost:3000/s/ldoxt3",
  "medium": "http://localhost:3000/s/1nhuch"
}

Type

array

/{id} get

GET: /images/{id}

Returns Image data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`4`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/images/{id}?project_id=4&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/notes

See Overview at http://rdoc.taxonworks.org/Note.html

/notes get

GET: /notes

Get all notes, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

note_id

Single ID for the note object to be found.

Property	Value
required	false
type	integer

note_id[]

Array of IDs for the notes to be found.

Property	Value
required	false
type	integer

note_object_id

Find all notes that reference any objects that have a note_object_id. This param should only be used in tandem with note_object_type.

Property	Value
required	false
type	integer

note_object_id[]

Array of identifiers for the note objects#, e.g., note_object_id[]=3254&note_object_id[]=197.

Property	Value
required	false
type	integer

note_object_type

Object type for the note, such as TaxonDetermination, TaxonName, Otu, etc.

Property	Value
required	false
type	string

note_object_type[]

Array of object types for the notes, note_object_type[]=TaxonDetermination&note_object_type[]=Otu. Should be used only with note_object_id[].

Property	Value
required	false
type	string

text

Text segment to be searched for in notes.

Property	Value
required	false
type	string

polymorphic

Property	Value
required	true
type	boolean

page

The page of notes result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of notes per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of notes per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of notes in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/notes get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/notes?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 1,
    "text": "SF reason: monotypy and original designation",
    "note_object_attribute": null,
    "note_object_id": 87,
    "note_object_type": "TaxonName",
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "note_object": {
      "global_id": "gid://taxon-works/Protonym/87"
    }
  },
  {
    "id": 2,
    "text": "SF reason: monotypy and original designation",
    "note_object_attribute": null,
    "note_object_id": 240,
    "note_object_type": "TaxonName",
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "note_object": {
      "global_id": "gid://taxon-works/Protonym/240"
    }
  }
]

Type

array

/{id} get

GET: /notes/{id}

Returns Note instance data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`2`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/notes/{id}?project_id=2&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/observation_matrices

See Overview at http://rdoc.taxonworks.org/ObservationMatrices.html extend[]= available for [rows, columns]

/observation_matrices get

GET: /observation_matrices

Get all observation_matrices, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

observation_matrix_id

Single ID for observation matrix.

Property	Value
required	false
type	integer

observation_matrix_id[]

Array of IDs for observation matrices.

Property	Value
required	false
type	integer array

page

The page of observation_matrices result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of observation_matrices per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of observation_matrices per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of observation_matrices in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/observation_matrices get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/observation_matrices?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id":8,"name":"matrix1",
    "created_by_id":775,
    "updated_by_id":775,
    "project_id":262,
    "created_at":"2020-06-29T16:09:39.944Z",
    "updated_at":"2020-06-29T16:09:39.944Z",
    "object_tag":"matrix1",
    "object_label":null,
    "global_id":"gid://taxon-works/ObservationMatrix/8",
    "base_class":"ObservationMatrix",
    "url_for":"https://sandbox.taxonworks.org/api/v1/observation_matrices",
    "object_url":"/observation_matrices/8",
    "is_media_matrix":true
  }
]

Type

array

/{id} get

GET: /observation_matrices/{id}

Returns Observation matrices data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/observation_matrices/{id}?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/{id}/key get

GET: /observation_matrices/{id}/key

Returns Observation matrices data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id}/key get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/observation_matrices/{id}/key?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/observations

See Overview at http://rdoc.taxonworks.org/Observation.html extend[]= available for [character_state, depictions]

/observations get

GET: /observations

Get all observations, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

character_state_id

Identifier for the character state.

Property	Value
required	false
type	integer

character_state_id[]

Identifiers for the character stated.

Property	Value
required	false
type	integer array

collection_object_id

Identifier for the collection object for which the observation is made.

Property	Value
required	false
type	integer

collection_object_id[]

Identifiers for the collection objects for which the observations are made.

Property	Value
required	false
type	integer array

descrendants

Include results for descendant OTUs if true.

Property	Value
required	false
type	boolean

descriptor_id

Identifier for the descriptor.

Property	Value
required	false
type	integer array

descriptor_id[]

Identifiers for these descriptors.

Property	Value
required	false
type	integer array

observation_object_global_id

Identifier for the observation object global id for which the observation is made.

Property	Value
required	false
type	integer

observation_object_type

Observation object type.

Property	Value
required	false
type	integer

observation_object_type[]

Observation object types.

Property	Value
required	false
type	integer array

observation_type

Observation type.

Property	Value
required	false
type	string

observation_type[]

Observation types.

Property	Value
required	false
type	string array

otu_id

ID for the OTU for which the observation is made.

Property	Value
required	false
type	integer

otu_id[]

IDs for the OTUs for which the observation is made.

Property	Value
required	false
type	integer array

taxon_name_id

ID for the taxon for which the observation is made.

Property	Value
required	false
type	integer

taxon_name_id[]

IDs for the taxa for which the observation is made.

Property	Value
required	false
type	integer array

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

image_id

ID for the image object to be found.

Property	Value
required	false
type	integer

image_id[]

Array of IDs for the image objects to be found.

Property	Value
required	false
type	integer

images

true: has images false: doesn't have images

Property	Value
required	false
type	boolean

note_exact

return Note if the exact text matches the note object.

Property	Value
required	false
type	boolean

note_text

Search for the exact text matching notes.

Property	Value
required	false
type	string

notes

True: only return objects with notes.

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_and[]

List of keyword IDs for tags for this model instances where all enumerated keywords are present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or[]

List of keyword IDs for tags for this model instances where any of the enumerated keywords are present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of observations result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of observations per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of observations per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of observations in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/observations get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/observations?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

{
  "id": 3,
  "descriptor_id": 3,
  "otu_id": 130037,
  "collection_object_id": null,
  "character_state_id": 7,
  "frequency": null,
  "continuous_value": null,
  "continuous_unit": null,
  "sample_n": null,
  "sample_min": null,
  "sample_max": null,
  "sample_median": null,
  "sample_mean": null,
  "sample_units": null,
  "sample_standard_error": null,
  "sample_standard_deviation": null,
  "presence": null,
  "description": null,
  "cached": null,
  "cached_column_label": null,
  "cached_row_label": null,
  "type": "Observation::Qualitative",
  "created_by_id": 2,
  "updated_by_id": 2,
  "project_id": 2,
  "created_at": "2020-10-12T18:58:02.305Z",
  "updated_at": "2020-10-12T18:58:02.305Z",
  "object_tag": "Foot smell: 3",
  "object_label": null,
  "global_id": "gid://taxon-works/Observation::Qualitative/3",
  "base_class": "Observation",
  "url_for": "http://localhost:3000/api/v1/observations/3",
  "object_url": "/observations/3"
}

Type

array

/{id} get

GET: /observations/{id}

Returns Observation instance data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`4`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/observations/{id}?project_id=4&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/otus

See Overview at http://rdoc.taxonworks.org/Otu.html extend[]= available for [parents]

/otus get

GET: /otus

Get all otus, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

asserted_distribution_ids[]

List of asserted distribution IDs.

Property	Value
required	false
type	integer array

biological_association_ids[]

List of biological_association IDs (via &extend[]=biological_association_ids).

Property	Value
required	false
type	integer array

data_attributes_attributes

[ :id, :_destroy, :controlled_vocabulary_term_id, :type, :attribute subject_id:, attribute_subject_type, :value ]

Property	Value
required	false
type	mixed parameter array

name

Name (label) of the OTU.

Property	Value
required	false
type	string

otu_id

ID for a single OTU.

Property	Value
required	false
type	integer

otu_ids[]

List of OTU IDs.

Property	Value
required	false
type	integer array

taxon_name_classification_ids[]

List of classification IDs.

Property	Value
required	false
type	integer array

taxon_name_id

ID for a given taxon

Property	Value
required	false
type	integer

taxon_name_ids[]

List of taxon name IDs.

Property	Value
required	false
type	integer array

taxon_name_relationships_ids[]

List of relationship IDs

Property	Value
required	false
type	integer array

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

data_attribute_exact_value

Whether or not to match on exact value:

Property	Value
required	false
type	boolean

data_attribute_predicate_id

ID of controlled vocabulary term predicate.

Property	Value
required	false
type	integer

data_attribute_predicate_id[]

Array of IDs of controlled vocabulary term predicates.

Property	Value
required	false
type	integer

data_attribute_value

Value to match against.

Property	Value
required	false
type	string

data_attribute_value[]

Array of values to match against.

Property	Value
required	false
type	string

data_attributes

True: result has a data_attribute; False: does not have a data_attribute; nil: not applied.

Property	Value
required	false
type	boolean

image_id

ID for the image object to be found.

Property	Value
required	false
type	integer

image_id[]

Array of IDs for the image objects to be found.

Property	Value
required	false
type	integer

images

true: has images false: doesn't have images

Property	Value
required	false
type	boolean

note_exact

return Note if the exact text matches the note object.

Property	Value
required	false
type	boolean

note_text

Search for the exact text matching notes.

Property	Value
required	false
type	string

notes

True: only return objects with notes.

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_and[]

List of keyword IDs for tags for this model instances where all enumerated keywords are present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or[]

List of keyword IDs for tags for this model instances where any of the enumerated keywords are present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of otus result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of otus per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of otus per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of otus in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/otus get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
  {
    "id": 1,
    "name": null,
    "taxon_name_id": 46,
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "created_at": "2022-12-23T06:31:38.230Z",
    "updated_at": "2022-12-23T06:31:38.230Z",
    "global_id": "gid://taxon-works/Otu/1",
    "object_tag": "<span class=\"otu_tag\"><span class=\"otu_tag_taxon_name\" title=\"46\"><i>Blatta</i></span> &#10003;</span>"
  },
  {
    "id": 2,
    "name": null,
    "taxon_name_id": 47,
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "created_at": "2022-12-23T06:31:38.382Z",
    "updated_at": "2022-12-23T06:31:38.382Z",
    "global_id": "gid://taxon-works/Otu/2",
    "object_tag": "<span class=\"otu_tag\"><span class=\"otu_tag_taxon_name\" title=\"47\"><i>Cicada</i></span> &#10003;</span>"
  },
  {
    "id": 3,
    "name": null,
    "taxon_name_id": 48,
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "created_at": "2022-12-23T06:31:38.469Z",
    "updated_at": "2022-12-23T06:31:38.469Z",
    "global_id": "gid://taxon-works/Otu/3",
    "object_tag": "<span class=\"otu_tag\"><span class=\"otu_tag_taxon_name\" title=\"48\"><i>Phasma</i></span> &#10003;</span>"
  }
]

Type

array

/autocomplete get

GET: /otus/autocomplete

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/autocomplete get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus/autocomplete?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/{id} get

GET: /otus/{id}

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Possible Responses

200

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus/{id}?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE BODY

Example

{
  "id": 109,
  "name": null,
  "taxon_name_id": 153,
  "created_by_id": 1,
  "updated_by_id": 1,
  "project_id": 2,
  "created_at": "2021-08-14T03:38:48.629Z",
  "updated_at": "2021-08-14T03:38:48.629Z",
  "global_id": "gid://taxon-works/Otu/109"
}

Type

array

/{otu_id}/inventory/content get

GET: /otus/{otu_id}/inventory/content

URI Parameters

otu_id

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

page

The page of content result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of content per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of content per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of content in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/{otu_id}/inventory/content get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus/{otu_id}/inventory/content?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[object Object]

Type

array

/{otu_id}/inventory/distribution get

GET: /otus/{otu_id}/inventory/distribution

URI Parameters

otu_id

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

page

The page of distribution result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of distribution per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of distribution per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of distribution in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/{otu_id}/inventory/distribution get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus/{otu_id}/inventory/distribution?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -80.2499,
          -1.4165,
          0
        ]
      },
      "properties": {
        "target": {
          "id": 109,
          "type": "Otu",
          "label": "Ripipteryx antennata Hebard, 1924"
        },
        "base": {
          "type": "CollectionObject",
          "id": 46663,
          "label": "CollectionObject 46663; http://orthoptera.speciesfile.org/Common/specimen/ShowSpecimen.aspx?SpecimenID=64394#2_1"
        },
        "shape": {
          "type": "Georeference",
          "id": 25196
        }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                -80.19332600000004,
                -3.0346935048828243,
                0.0
              ],
              [
                -80.12192600000003,
                -3.0146935048828283,
                0.0
              ],
              [
                -80.12672600000005,
                -3.0166935048828236,
                0.0
              ],
              [
                -80.19332600000004,
                -3.0346935048828243,
                0.0
              ]
            ]
          ],
          [
            [
              [
                -79.83862600000003,
                -2.6419935048828336,
                0.0
              ],
              [
                -79.85582600000004,
                -2.6446935048828237,
                0.0
              ],
              [
                -79.87922600000005,
                -2.6396935048828283,
                0.0
              ],
              [
                -79.83862600000003,
                -2.6419935048828336,
                0.0
              ]
            ]
          ],
          [
            [
              [
                -78.91222600000003,
                1.2392064951171733,
                0.0
              ],
              [
                -78.95692600000004,
                1.2353064951171717,
                0.0
              ],
              [
                -78.96252600000003,
                1.236906495117168,
                0.0
              ],
              [
                -78.91222600000003,
                1.2392064951171733,
                0.0
              ]
            ]
          ]
        ]
      },
      "properties": {
        "base": {
          "type": "AssertedDistribution",
          "id": 39611,
          "label": "Ripipteryx antennata Hebard, 1924 in Ecuador"
        },
        "shape": {
          "type": "GeographicArea",
          "id": 33707
        },
        "is_absent": null,
        "target": {
          "id": 109,
          "type": "Otu",
          "label": "Ripipteryx antennata Hebard, 1924"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -80.2499,
          -1.4165,
          0
        ]
      },
      "properties": {
        "target": {
          "id": 109,
          "type": "Otu",
          "label": "Ripipteryx antennata Hebard, 1924"
        },
        "base": {
          "type": "TypeMaterial",
          "id": 19498,
          "label": "holotype of Ripipteryx antennata Hebard, 1924"
        },
        "shape": {
          "type": "Georeference",
          "id": 25196
        }
      }
    }
  ],
  "properties": {
    "target": {
      "id": 109,
      "label": "Ripipteryx antennata Hebard, 1924",
      "type": "Otu"
    }
  }
}

Type

array

/{otu_id}/inventory/images get

GET: /otus/{otu_id}/inventory/images

URI Parameters

otu_id

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

page

The page of images result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of images per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of images per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of images in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/{otu_id}/inventory/images get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus/{otu_id}/inventory/images?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 9,
    "height": 67,
    "width": 309,
    "image_file_fingerprint": "84857aac680b69596446ca5541868eca",
    "image_file_file_name": "110803",
    "image_file_file_size": 10007,
    "created_by_id": 1,
    "updated_by_id": 1,
    "pixels_to_centimeter": null,
    "original": "http://localhost:3000/s/iphrhk",
    "thumb": "http://localhost:3000/s/k667zm",
    "medium": "http://localhost:3000/s/gka1x9"
  },
  {
    "id": 10,
    "height": 282,
    "width": 119,
    "image_file_fingerprint": "3bf3244d41701e1c43c9160d95fdeb0e",
    "image_file_file_name": "110804",
    "image_file_file_size": 10085,
    "created_by_id": 1,
    "updated_by_id": 1,
    "pixels_to_centimeter": null,
    "original": "http://localhost:3000/s/dtb11k",
    "thumb": "http://localhost:3000/s/2ibb55",
    "medium": "http://localhost:3000/s/aacvn1"
  },
  {
    "id": 11,
    "height": 277,
    "width": 320,
    "image_file_fingerprint": "dbcec755a25b3640bb0510f2854a5fed",
    "image_file_file_name": "110805",
    "image_file_file_size": 12816,
    "created_by_id": 1,
    "updated_by_id": 1,
    "pixels_to_centimeter": null,
    "original": "http://localhost:3000/s/5u0wnt",
    "thumb": "http://localhost:3000/s/i844zm",
    "medium": "http://localhost:3000/s/k20dv2"
  }
]

Type

array

/{id}/inventory/nomenclature_citations get

GET: /otus/{id}/inventory/nomenclature_citations

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

page

The page of nomenclature_citations result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of nomenclature_citations per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of nomenclature_citations per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of nomenclature_citations in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/{id}/inventory/nomenclature_citations get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus/{id}/inventory/nomenclature_citations?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "source": {
      "id": 3811,
      "name": "Günther, K.K. (1969) Revision der Familie Rhipipterygidae Chopard, 1949 (Saltatoria, Insecta). <i>Mitteilungen aus dem Zoologischen Museum in Berlin</i>, 45(2), 259–425.",
      "short_name": "Günther, 1969"
    },
    "names": [
      "<i>Ripipteryx crassicornis</i> Günther, 1969"
    ]
  },
  {
    "source": {
      "id": 6900,
      "name": "Günther, K.K. (1980) Katalog der Caelifera-Unterordnung Tridactyloidea (Insecta). <i>Deutsche entomologische Zeitschrift</i>, 27(1-3), 149–178.",
      "short_name": "Günther, 1980"
    },
    "names": [
      "<i>Ripipteryx crassicornis</i> Günther, 1969"
    ]
  }
]

Type

array

/{id}/inventory/taxonomy get

GET: /otus/{id}/inventory/taxonomy

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

page

The page of taxonomy result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of taxonomy per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of taxonomy per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of taxonomy in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/{id}/inventory/taxonomy get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus/{id}/inventory/taxonomy?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

{
  "otu_id": 109,
  "name": "<i>Ripipteryx crassicornis</i> Günther, 1969",
  "otu_clones": [],
  "similar_otus": {
    "127281": "Rhipipteryx crassicornis: Ripipteryx crassicornis Günther, 1969"
  },
  "nomenclatural_synonyms": [],
  "common_names": [],
  "descendants": [],
  "leaf_node": true
}

Type

array

/{id}/inventory/type_material get

GET: /otus/{id}/inventory/type_material

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

page

The page of type_material result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of type_material per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of type_material per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of type_material in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/{id}/inventory/type_material get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/otus/{id}/inventory/type_material?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

{
  "type_materials_catalog_labels": [
    {
      "type_type": "holotype",
      "label": "Holotype; male; 846576f6-6a1c-46bc-b480-6350ecc2aa7a; deposited at: California Academy of Sciences (CAS)"
    }
  ]
}

Type

array

/people

See Overview at http://rdoc.taxonworks.org/Person.html extend[]= available for [roles]

/people get

GET: /people

Get all people, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

active_after_year

Restrict search to persons active after this year date

Property	Value
required	false
type	integer

active_before_year

Restrict search to persons active before this year date

Property	Value
required	false
type	integer

born_after_year

Restrict search to persons who were born after this year date

Property	Value
required	true
type	string

born_before_year

Restrict search to persons who were born before this year date

Property	Value
required	false
type	integer

died_after_year

Restrict search to persons who died after this year date

Property	Value
required	false
type	integer

died_before_year

Restrict search to persons who died before this year date

Property	Value
required	false
type	integer

first_name

Filter by person first name or fragment. Matching is case insensitive. Use " " for "and". See also exact.

Property	Value
required	false
type	string

identifier

Identifier contains the identifier string.

Property	Value
required	false
type	string

identifier_end

Identifier ends with the identifier string.

Property	Value
required	false
type	string

identifier_exact

Identifier strng must exactly match.

Property	Value
required	false
type	string

identifier_start

Identifier starts with the identifier string.

Property	Value
required	false
type	string

last_name

Filter by person last name or fragment. Matching is case insensitive. Use " " for "and". See also exact.

Property	Value
required	false
type	string

last_name_starts_with

Filter by person last name fragment (from beginning). Matching is case insensitive. Use " " for "and". See also exact.

Property	Value
required	false
type	string
examples	`Murp`

person_wildcard[]

Wildcard parameter(s)

Property	Value
required	false
type	string

role

Filter by a person's role, e.g., SourceAuthor, SourceEditor, SourceSource, TaxonNameAuthor. Matching is case insensitive. Use " " for "and". See also exact.

Property	Value
required	false
type	string array
examples	`SourceAuthor`

role[]

Filter by person role(s), e.g., &role[]=SourceAuthor&role[]=TaxonNameAuthor.

Property	Value
required	false
type	string array
examples	`SourceAuthor`

project_id

The project for the source search

Property	Value
required	true
type	integer
examples	`2`

name

Property	Value
required	true
type	description:\| Search for names containing this string. type

tags

Optional tags for person search.

Property	Value
required	false
type	boolean

user_date_end

User

Property	Value
required	false
type	string

user_date_start

User

Property	Value
required	false
type	string

data_attribute_exact_value

Whether or not to match on exact value:

Property	Value
required	false
type	boolean

data_attribute_predicate_id

ID of controlled vocabulary term predicate.

Property	Value
required	false
type	integer

data_attribute_predicate_id[]

Array of IDs of controlled vocabulary term predicates.

Property	Value
required	false
type	integer

data_attribute_value

Value to match against.

Property	Value
required	false
type	string

data_attribute_value[]

Array of values to match against.

Property	Value
required	false
type	string

data_attributes

True: result has a data_attribute; False: does not have a data_attribute; nil: not applied.

Property	Value
required	false
type	boolean

note_exact

return Note if the exact text matches the note object.

Property	Value
required	false
type	boolean

note_text

Search for the exact text matching notes.

Property	Value
required	false
type	string

notes

True: only return objects with notes.

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_and[]

List of keyword IDs for tags for this model instances where all enumerated keywords are present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or[]

List of keyword IDs for tags for this model instances where any of the enumerated keywords are present.

Property	Value
required	false
type	integer

page

The page of people result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of people per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of people per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of people in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/people get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/people?last_name_starts_with=Murp&role=SourceAuthor&role[]=SourceAuthor&project_id=2&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 24087,
    "type": "Person::Vetted",
    "last_name": "Murphey",
    "first_name": "Katherine J.",
    "suffix": null,
    "prefix": null,
    "cached": "Murphey, Katherine J.",
    "year_born": null,
    "year_died": null,
    "year_active_start": 2019,
    "year_active_end": 2019,
    "created_by_id": 24,
    "updated_by_id": 1,
    "created_at": "2019-10-03T09:02:00.000Z",
    "updated_at": "2020-09-17T02:13:44.835Z",
    "global_id": "gid://taxon-works/Person::Vetted/24087"
  },
  {
    "id": 24492,
    "type": "Person::Vetted",
    "last_name": "Murphy",
    "first_name": "Raymond J.",
    "suffix": null,
    "prefix": null,
    "cached": "Murphy, Raymond J.",
    "year_born": null,
    "year_died": null,
    "year_active_start": 2020,
    "year_active_end": 2020,
    "created_by_id": 24,
    "updated_by_id": 1,
    "created_at": "2020-01-27T09:04:00.000Z",
    "updated_at": "2020-09-17T02:14:16.888Z",
    "global_id": "gid://taxon-works/Person::Vetted/24492"
  }
]

Type

array

/{id} get

GET: /people/{id}

returns people data for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/people/{id}?token=eUUB4dQCCWlLGzksimEqNQ" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/sources

See Overview at http://rdoc.taxonworks.org/Source.html extend[]= available for [roles, documents]

/sources get

GET: /sources

Get all sources, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

author

Filter by author (inside author property). Matching is case insensitive. Use " " for "and". See also exact.

Property	Value
required	false
type	string

author_id

Filter by this author ID.

Property	Value
required	false
type	integer

author_id[]

Filter by author IDs

Property	Value
required	false
type	integer array

author_id_or

Find collecting events with ANY one of these authors (true) or ALL of these collectors (false/nil)

Property	Value
required	false
type	boolean

bibtex_type

one of the allowed BibTeX types

Property	Value
required	false
type	string

bibtex_type[]

one of the allowed BibTeX types

Property	Value
required	false
type	string array

citation_object_type

Get sources with one of these enumerated types:

Property	Value
required	false
type	string
oneOf	TaxonDetermination, Image, Confidence, Otu, AssertedDistribution, DataAttribute, ImportAttribute, TaxonNameRelationship, TaxonName, CollectionObject, TypeMaterial

citation_object_type[]

Get sources with these enumerated types:

Property	Value
required	false
type	string array

citations

true: sources with citations; false: sources without citations; nil: not applied.

Property	Value
required	false
type	boolean

citations_on_otus

ignored if taxon_name_id is not provided; if true then also include sources linked to OTUs that are in the scope of taxon_name_id

Property	Value
required	false
type	boolean

descendants

return all sources in Citations linked to this TaxonNameID or its descendants.

Property	Value
required	false
type	string

documents

get sources matching documents

Property	Value
required	false
type	boolean

empty

A source core attribute (author, bibtex_type, title) must have no value.

Property	Value
required	false
type	string

empty[]

the provided source core attributes (author, bibtex_type, title) must have no value.

Property	Value
required	false
type	string array

exact_author

Metadata for only the exact author string provided (inside author property). Matching is case insensitive.

Property	Value
required	false
type	string

exact_title

Metadata selected for only exact title match

Property	Value
required	false
type	boolean

identifier

Identifier associated with source

Property	Value
required	false
type	string

identifier_end

Last part of identifier associated with source

Property	Value
required	false
type	string

identifier_exact

Exact identifier associated with source

Property	Value
required	false
type	string

identifier_start

First part of identifier associated with source

Property	Value
required	false
type	string

ids[]

Filter by source IDs

Property	Value
required	false
type	integer array

in_project

Use requires project_id; true: results for project_id; false: results not in project_id; nil: nat applied.

Property	Value
required	false
type	boolean

keyword_id_and

List of keyword IDs for sources where all enumerated keywords are present.

Property	Value
required	false
type	integer array

keyword_id_and[]

List of keyword IDs for sources where all enumerated keywords are present.

Property	Value
required	false
type	integer array

keyword_id_or

List of keyword IDs for sources where all enumerated keywords are present.

Property	Value
required	false
type	integer array

keyword_id_or[]

List of keyword IDs for sources where any of the enumerated keywords are present.

Property	Value
required	false
type	integer array

nomenclature

include nomenclature metadata

Property	Value
required	false
type	boolean

not_empty

a source core attributes (author, bibtex_type, title) must have a value.

Property	Value
required	false
type	string array

not_empty[]

the provided source core attributes (author, bibtex_type, title) must have a value.

Property	Value
required	false
type	string array

notes

include notes metadata

Property	Value
required	false
type	boolean

project_id

The project for the source search, must be used with in_project.

Property	Value
required	true
type	integer

query_term

obsolescent query item

Property	Value
required	false
type	string

roles

include metadata for roles

Property	Value
required	false
type	boolean

serial

true: with serial_id; false: without_serial_id; nil: both

Property	Value
required	true
type	string

serial_id

The serial ID associated with the source.

Property	Value
required	false
type	integer

serial_id[]

The serial IDs associated with the source.

Property	Value
required	false
type	integer array

source_id

get data for a source by ID

Property	Value
required	false
type	integer

source_id[]

get data for sources by IDs

Property	Value
required	false
type	integer array

source_type

type of source, e.g., Source::BibTex, Source::verbatim, Source::human.

Property	Value
required	false
type	string

taxon_name_id

return all sources in Citations linked to this TaxonNameID (or descendants option to this TaxonName)

Property	Value
required	false
type	string

taxon_name_id[]

return all sources in Citations linked to these TaxonNameIDs (or descendants option to this TaxonName)

Property	Value
required	false
type	string

title

title of the source, e.g., "Studies in American Tettigoniidae"

Property	Value
required	false
type	string

topic_id

Get source metadata associated with these topic IDs

Property	Value
required	false
type	integer

topic_id[]

Get source metadata associated with these topic IDs

Property	Value
required	false
type	integer

user_date_end

Limit search to user dates prior

Property	Value
required	false
type	string

user_date_start

Limit search to user dates later

Property	Value
required	false
type	string

with_doi

include metadata for sources having Digital Object Identifier

Property	Value
required	false
type	boolean

with_title

true: with a title; false: without a title; nil: both

Property	Value
required	false
type	boolean

year_end

end year of the source date range

Property	Value
required	false
type	integer

year_start

start year of the source date range

Property	Value
required	false
type	integer

note_exact

return Note if the exact text matches the note object.

Property	Value
required	false
type	boolean

note_text

Search for the exact text matching notes.

Property	Value
required	false
type	string

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of sources result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of sources per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of sources per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of sources in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/sources get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/sources?page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 2,
    "serial_id": 1514,
    "address": null,
    "annote": null,
    "author": "Karny, Heinrich Hugo",
    "booktitle": null,
    "chapter": null,
    "crossref": null,
    "edition": null,
    "editor": null,
    "howpublished": null,
    "institution": null,
    "journal": "Zoologische Annalen",
    "key": null,
    "month": null,
    "note": null,
    "number": null,
    "organization": null,
    "pages": "202-208",
    "publisher": null,
    "school": null,
    "series": null,
    "title": "Bemerkungen zu dem Linné'schen Gattungsnamen \"Tettigonia\"",
    "type": "Source::Bibtex",
    "volume": "2",
    "doi": null,
    "abstract": null,
    "copyright": null,
    "language": null,
    "stated_year": null,
    "verbatim": null,
    "cached": "Karny, H.H. (1908) Bemerkungen zu dem Linné'schen Gattungsnamen \"Tettigonia\". <i>Zoologische Annalen</i> 2, 202–208.",
    "cached_author_string": "Karny",
    "bibtex_type": "article",
    "created_by_id": 1,
    "updated_by_id": 19,
    "cached_nomenclature_date": "1908-12-31",
    "day": null,
    "year": 1908,
    "isbn": null,
    "issn": null,
    "verbatim_contents": null,
    "verbatim_keywords": null,
    "language_id": null,
    "translator": null,
    "year_suffix": null,
    "url": "http://www.biodiversitylibrary.org/item/109156#page/218/mode/1up",
    "created_at": "2013-02-12T18:22:00.000Z",
    "updated_at": "2017-07-22T15:32:00.000Z",
    "object_tag": "Karny, H.H. (1908) Bemerkungen zu dem Linné'schen Gattungsnamen \"Tettigonia\". <i>Zoologische Annalen</i> 2, 202–208.",
    "object_label": "Karny, 1908",
    "global_id": "gid://taxon-works/Source::Bibtex/2",
    "base_class": "Source",
    "url_for": "http://localhost:3000/api/v1/sources",
    "object_url": "/sources/2",
    "source_in_project": false,
    "project_source_id": null
  },
  {
    "id": 6,
    "serial_id": null,
    "address": "Indianapolis",
    "annote": null,
    "author": "Blatchley, W.S.",
    "booktitle": "Orthoptera of northeastern America with special reference to the faunas of Indiana and Florida",
    "chapter": null,
    "crossref": null,
    "edition": null,
    "editor": null,
    "howpublished": null,
    "institution": null,
    "journal": null,
    "key": null,
    "month": null,
    "note": null,
    "number": null,
    "organization": null,
    "pages": "781 pp., 5 pls.",
    "publisher": "Nature Publishing Co.",
    "school": null,
    "series": null,
    "title": null,
    "type": "Source::Bibtex",
    "volume": null,
    "doi": null,
    "abstract": null,
    "copyright": null,
    "language": null,
    "stated_year": null,
    "verbatim": null,
    "cached": "Blatchley, W.S. (1920) Orthoptera of northeastern America with special reference to the faunas of Indiana and Florida Nature Publishing Co., Indianapolis. Available from: http://www.biodiversitylibrary.org/item/16768 781 pp., 5 pls.",
    "cached_author_string": "Blatchley",
    "bibtex_type": "book",
    "created_by_id": 1,
    "updated_by_id": 19,
    "cached_nomenclature_date": "1920-12-31",
    "day": null,
    "year": 1920,
    "isbn": null,
    "issn": null,
    "verbatim_contents": null,
    "verbatim_keywords": null,
    "language_id": null,
    "translator": null,
    "year_suffix": null,
    "url": "http://www.biodiversitylibrary.org/item/16768",
    "created_at": "2013-02-12T18:22:00.000Z",
    "updated_at": "2012-05-11T11:17:00.000Z",
    "object_tag": "Blatchley, W.S. (1920) Orthoptera of northeastern America with special reference to the faunas of Indiana and Florida Nature Publishing Co., Indianapolis. Available from: http://www.biodiversitylibrary.org/item/16768 781 pp., 5 pls.",
    "object_label": "Blatchley, 1920",
    "global_id": "gid://taxon-works/Source::Bibtex/6",
    "base_class": "Source",
    "url_for": "http://localhost:3000/api/v1/sources",
    "object_url": "/sources/6",
    "source_in_project": false,
    "project_source_id": null
  }
]

Type

array

/{id} get

GET: /sources/{id}

Returns Sources metadata for ID in URI.

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/sources/{id}?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/taxon_name_classifications

See Overview at http://rdoc.taxonworks.org/TaxonNameClassification.html

/taxon_name_classifications get

GET: /taxon_name_classifications

Get all taxon_name_classifications, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

taxon_name_id

A single ID for the taxon name.

Property	Value
required	false
type	string integer

taxon_name_id[]

Array of IDs for the taxon names.

Property	Value
required	false
type	integer array

taxon_name_classification_type

Type of classification

Property	Value
required	false
type	string
examples	`TaxonNameClassification::Iczn::Unavailable::NomenNudum`

taxon_name_classification_type[]

Array of classifications

Property	Value
required	false
type	string array

taxon_name_classification_set

One of 'validating', 'invalidating', 'exceptions'

Property	Value
required	false
type	string

taxon_name_classification_set[]

One or more of 'validating', 'invalidating', 'exceptions'

Property	Value
required	false
type	string array

page

The page of taxon_name_classifications result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of taxon_name_classifications per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of taxon_name_classifications per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of taxon_name_classifications in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/taxon_name_classifications get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_name_classifications?taxon_name_classification_type=TaxonNameClassification::Iczn::Unavailable::NomenNudum&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 15,
    "taxon_name_id": 115,
    "type": "TaxonNameClassification::Iczn::Unavailable::NomenNudum",
    "created_by_id": 5,
    "updated_by_id": 24,
    "project_id": 2,
    "created_at": "2013-02-12T18:23:00.000Z",
    "updated_at": "2018-09-27T08:31:00.000Z",
    "object_tag": "<i>Mirhipipteryx lobata</i> (nomen nudum)",
    "url": "http://localhost:3000/taxon_name_classifications/15.json",
    "global_id": "gid://taxon-works/TaxonNameClassification::Iczn::Unavailable::NomenNudum/15"
  },
  {
    "id": 82,
    "taxon_name_id": 650,
    "type": "TaxonNameClassification::Iczn::Unavailable::NomenNudum",
    "created_by_id": 24,
    "updated_by_id": 24,
    "project_id": 2,
    "created_at": "2017-02-10T10:02:00.000Z",
    "updated_at": "2019-09-13T13:49:00.000Z",
    "object_tag": "<i>Saussurella brachycornis</i> Deng, 2016 (nomen nudum)",
    "url": "http://localhost:3000/taxon_name_classifications/82.json",
    "global_id": "gid://taxon-works/TaxonNameClassification::Iczn::Unavailable::NomenNudum/82"
  }
]

Type

array

/{id} get

GET: /taxon_name_classifications/{id}

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_name_classifications/{id}?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/taxon_name_relationships

See Overview at http://rdoc.taxonworks.org/TaxonNameRelationship.html

/taxon_name_relationships get

GET: /taxon_name_relationships

Get all taxon_name_relationships, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

object_taxon_name_id

A single ID for the object taxon name.

Property	Value
required	false
type	string integer

object_taxon_name_id[]

Array of IDs for the onject taxon names.

Property	Value
required	false
type	integer array

subject_taxon_name_id

A single ID for the subject taxon name.

Property	Value
required	false
type	string integer
examples	`377`

subject_taxon_name_id[]

Array of IDs for the subject taxon names.

Property	Value
required	false
type	integer array

taxon_name_id

A single ID for the taxon name as either subject or object.

Property	Value
required	false
type	string integer
examples	`377`

taxon_name_id[]

Array of IDs for the taxon names as either subject or object.

Property	Value
required	false
type	integer array

taxon_name_relationship_set

One of 'validating', 'invalidating', 'exceptions'

Property	Value
required	false
type	string

taxon_name_relationship_set[]

One or more of 'validating', 'invalidating', 'exceptions'

Property	Value
required	false
type	string array

taxon_name_relationship_type

One exact NOMEN/Ruby class/type, e.g., "TaxonNameRelationship::Iczn::Invalidating"

Property	Value
required	false
type	string

taxon_name_relationship_type[]

One or more exact NOMEN/Ruby class/type

Property	Value
required	false
type	string array

page

The page of taxon_name_relationships result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of taxon_name_relationships per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of taxon_name_relationships per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of taxon_name_relationships in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/taxon_name_relationships get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_name_relationships?subject_taxon_name_id=377&taxon_name_id=377&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 17584,
    "subject_taxon_name_id": 10444,
    "object_taxon_name_id": 10443,
    "subject_status_tag": "unavailable or invalid, linked to",
    "object_status_tag": "valid for",
    "type": "TaxonNameRelationship::Iczn::Invalidating",
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "created_at": "2021-08-14T10:40:27.135Z",
    "updated_at": "2021-08-14T10:40:27.135Z",
    "inverse_assignment_method": "iczn_invalid",
    "assignment_method": "iczn_set_as_invalid_of",
    "subject_name": "Dichromatos corupa Carbonell & Mesa, 2007",
    "object_name": "Dichromatos corupa Carbonell & Mesa, 2011",
    "global_id": "gid://taxon-works/TaxonNameRelationship::Iczn::Invalidating/17584"
  },
  {
    "id": 17585,
    "subject_taxon_name_id": 10446,
    "object_taxon_name_id": 10445,
    "subject_status_tag": "unavailable or invalid, linked to",
    "object_status_tag": "valid for",
    "type": "TaxonNameRelationship::Iczn::Invalidating",
    "created_by_id": 1,
    "updated_by_id": 1,
    "project_id": 2,
    "created_at": "2021-08-14T10:40:27.185Z",
    "updated_at": "2021-08-14T10:40:27.185Z",
    "inverse_assignment_method": "iczn_invalid",
    "assignment_method": "iczn_set_as_invalid_of",
    "subject_name": "Dichromatos montanus Carbonell & Mesa, 2007",
    "object_name": "Dichromatos montanus Carbonell & Mesa, 2011",
    "global_id": "gid://taxon-works/TaxonNameRelationship::Iczn::Invalidating/17585"
  }
]

Type

array

/{id} get

GET: /taxon_name_relationships/{id}

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_name_relationships/{id}?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/taxon_names

See Overview at http://rdoc.taxonworks.org/TaxonName.html extend[]= available for [otus, roles, ancestor_ids, parent, children, type_taxon_name_relationship]

/taxon_names get

GET: /taxon_names

Get all taxon_names, optionally filtered

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

ancestors

taxon_name_id must be supplied. Works as AND clause with descendants

Property	Value
required	false
type	boolean

author

Filter by authors (inside cached_author_year property). Matching is case insensitive. Use "&" for "and". See also author_exact.

Property	Value
required	false
type	string

author_exact

Filter by authors (inside cached_author_year property). Matching is case insensitive. Use "&" for "and". See also exact.

Property	Value
required	false
type	boolean

authors

When true then only return taxon names that have an author string present.

Property	Value
required	true
type	boolean
oneOf	true, false

collecting_event_id

ID for associated collecting event.

Property	Value
required	false
type	integer array

collecting_event_id[]

List of IDs for associated collecting events.

Property	Value
required	false
type	integer array

collection_object_id

ID for associated collection object.

Property	Value
required	false
type	integer

collection_object_id[]

List of IDs for associated collection objects.

Property	Value
required	false
type	integer array

combination_taxon_name_id[]

List of taxon_name_ids for which all Combinations will be returned.

Property	Value
required	false
type	integer array

descendants

Filter by parenthood. When set to true and one or more taxon_name_id values are provided then the request matches taxa which are children of at least one of the taxa specified by the taxon_name_ids. Has no effect if taxon_name_id is not provided.

Property	Value
required	true
type	boolean

descendants_max_depth

A positive integer indicating how many levels deep of descendants to retrieve. Ignored when descendants is false/unspecified.

Property	Value
required	true
type	boolean

etymology

true: result if the name has etymology; false: result for no etymologu.

Property	Value
required	true
type	boolean

exact

true: filter matching must be exact; false/nil: partial matches are allowed.

Property	Value
required	true
type	boolean

leaves

true: filters by names having no descendents; false: with descendants; nil: not applied.

Property	Value
required	false
type	boolean

name

Filter to apply on full taxon name (cached property). Matching is case insensitive. See also name_exact.

Property	Value
required	false
type	string

name[]

Filter to apply on full taxon name (cached property). Matching is case insensitive. See also name_exact.

Property	Value
required	false
type	string array

name_exact

true: apply on full taxon name (cached property). Matching is case insensitive. See also name.

Property	Value
required	false
type	boolean

nomenclature_code

Filter by nomenclature code.

Property	Value
required	false
type	string
oneOf	ICZN, ICBN, ICN, ICTV

nomenclature_group

Filter by nomenclature group.

Property	Value
required	false
type	string
oneOf	Higher, Family, Genus, Species

not_specified

Filter by whether the name has 'NOT SPECIFIED' in one of the cache values. true - 'NOT SPECIFIED' is present in any value; false: text is absent; nil: either present or absent.

Property	Value
required	false
type	boolean

original_combination

true: name has at least one element of original combination false: name has no element of original combination nil: ignored

Property	Value
required	true
type	boolean

otus

When true then only return taxon names that are linked to one or more Otus.

Property	Value
required	false
type	boolean

parent_id

Return the taxon names with this parent_id (as taxon_name_id).

Property	Value
required	false
type	integer

parent_id[]

Return the taxon names with these parent_ids (as taxon_name_id).

Property	Value
required	false
type	integer array

rank

The full rank class, or any base, like NomenclaturalRank::Iczn::SpeciesGroup::Species, Iczn::SpeciesGroup::Species.

Property	Value
required	false
type	string

rank[]

The full rank class, or any base, like NomenclaturalRank::Iczn::SpeciesGroup::Species, Iczn::SpeciesGroup::Species.

Property	Value
required	false
type	string array

taxon_name_author_id_or

true: treat IDs as "and" (only collection objects with all and only all will match) false or nil: treat Ids as "or".

Property	Value
required	true
type	string

taxon_name_id

Return only the taxon name with this ID. To also return children see descendants.

Property	Value
required	false
type	integer array

taxon_name_id[]

Return only taxon names with these ids. E.g., "?taxon_name_id[]=5&taxon_name_id[]=194". To also return children see descendants.

Property	Value
required	false
type	integer array

taxon_name_relationship[]

:subject_taxon_name_id, :object_taxon_name_id, :type

Property	Value
required	false
type	string array

taxon_name_relationship_type[]

Filter by names having relationships of these types, e.g., TaxonNameRelationship::Iczn::Invalidating

Property	Value
required	false
type	string array

taxon_name_type[]

Return only taxon names of the provided class. Case sensitive.

Property	Value
required	false
type	string
oneOf	Protonym, Combination, Hybrid
examples	`Protonym`

type_metadata

Boolean. When true then only return taxon names that are linked to type specimen material (collection object).

Property	Value
required	false
type	boolean
oneOf	true, false

validify

if true then for each name in the result its valid name is returned

Property	Value
required	false
type	boolean

validity

Filter by validity. True if only valid, false if only invalid, nil if both

Property	Value
required	false
type	boolean

year

Filter by authority year (inside cached_author_year property). Format is 'YYYY'.

Property	Value
required	false
type	string

year_end

Filter by authority year (inside cached_nomenclature_date property). Format is 'YYYY'.

Property	Value
required	false
type	string

year_start

Filter by authority year (inside cached_nomenclature_date property). Format is 'YYYY'.

Property	Value
required	false
type	string

citations

true: with Citations false: without Citations nil: ignored

Property	Value
required	false
type	boolean

citation_documents

true: has Citations, sources have documents false: has Citations, sources don't have documents nil: ignored

Property	Value
required	false
type	boolean

origin_citation

true: with Origin Citation false: without Origin Citations nil: ignored

Property	Value
required	false
type	boolean

data_attribute_exact_value

Whether or not to match on exact value:

Property	Value
required	false
type	boolean

data_attribute_predicate_id

ID of controlled vocabulary term predicate.

Property	Value
required	false
type	integer

data_attribute_predicate_id[]

Array of IDs of controlled vocabulary term predicates.

Property	Value
required	false
type	integer

data_attribute_value

Value to match against.

Property	Value
required	false
type	string

data_attribute_value[]

Array of values to match against.

Property	Value
required	false
type	string

data_attributes

True: result has a data_attribute; False: does not have a data_attribute; nil: not applied.

Property	Value
required	false
type	boolean

image_id

ID for the image object to be found.

Property	Value
required	false
type	integer

image_id[]

Array of IDs for the image objects to be found.

Property	Value
required	false
type	integer

images

true: has images false: doesn't have images

Property	Value
required	false
type	boolean

note_exact

return Note if the exact text matches the note object.

Property	Value
required	false
type	boolean

note_text

Search for the exact text matching notes.

Property	Value
required	false
type	string

notes

True: only return objects with notes.

Property	Value
required	false
type	boolean

keyword_id_and

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_and[]

List of keyword IDs for tags for this model instances where all enumerated keywords are present.

Property	Value
required	false
type	integer

keyword_id_or

Keyword ID for tags for this model instances where this keyword is present.

Property	Value
required	false
type	integer

keyword_id_or[]

List of keyword IDs for tags for this model instances where any of the enumerated keywords are present.

Property	Value
required	false
type	integer

tags

true: return objects that have tags.

Property	Value
required	false
type	boolean

page

The page of taxon_names result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of taxon_names per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of taxon_names per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of taxon_names in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/taxon_names get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names?taxon_name_type[]=Protonym&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

[
  {
    "id": 64,
    "name": "Shurabia",
    "parent_id": 24,
    "cached": "Shurabia",
    "cached_html": "<i>Shurabia</i>",
    "feminine_name": null,
    "masculine_name": null,
    "nomenclatural_code": "iczn",
    "neuter_name": null,
    "etymology": null,
    "year_of_publication": null,
    "verbatim_author": null,
    "rank": "genus",
    "rank_string": "NomenclaturalRank::Iczn::GenusGroup::Genus",
    "type": "Protonym",
    "created_by_id": 19,
    "updated_by_id": 19,
    "project_id": 2,
    "cached_valid_taxon_name_id": 64,
    "cached_original_combination": null,
    "cached_original_combination_html": null,
    "cached_author_year": null,
    "cached_secondary_homonym": null,
    "cached_primary_homonym": "Shurabia",
    "cached_is_valid": true,
    "created_at": "2020-07-21T14:11:00.000Z",
    "updated_at": "2020-07-21T14:11:00.000Z",
    "verbatim_name": null,
    "year": null,
    "name_string": "Shurabia",
    "original_combination": null
  },
  {
    "id": 65,
    "name": "Homalophlebia",
    "parent_id": 24,
    "cached": "Homalophlebia",
    "cached_html": "<i>Homalophlebia</i>",
    "feminine_name": null,
    "masculine_name": null,
    "nomenclatural_code": "iczn",
    "neuter_name": null,
    "etymology": null,
    "year_of_publication": null,
    "verbatim_author": null,
    "rank": "genus",
    "rank_string": "NomenclaturalRank::Iczn::GenusGroup::Genus",
    "type": "Protonym",
    "created_by_id": 19,
    "updated_by_id": 19,
    "project_id": 2,
    "cached_valid_taxon_name_id": 65,
    "cached_original_combination": null,
    "cached_original_combination_html": null,
    "cached_author_year": null,
    "cached_secondary_homonym": null,
    "cached_primary_homonym": "Homalophlebia",
    "cached_is_valid": true,
    "created_at": "2021-06-17T21:03:00.000Z",
    "updated_at": "2021-06-17T21:03:00.000Z",
    "verbatim_name": null,
    "year": null,
    "name_string": "Homalophlebia",
    "original_combination": null
  }
]

Type

array

/autocomplete get

GET: /taxon_names/autocomplete

Returns a single TaxonName instance with related data included.

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

exact

If true TaxonName.name must match the search term exactly to be returned (i.e. no fuzzy matching)

Property	Value
required	false
type	boolean
examples	`true`

no_leaves

If 'true' names with no children will be excluded.

Property	Value
required	false
type	boolean
examples	`true`

nomenclature_group[]

Filter by nomenclature group.

Property	Value
required	false
type	string array
examples	`Genus&nomenclature_group[]=Species`

parent_id[]

Filter by all children of these parents. Filter includes supplied parents.

Property	Value
required	false
type	array

project_id

Project identifier. In the absence of a project token you must provide this parameter.

Property	Value
required	false
type	integer
examples	`1`

term

The search term by which names will be filtered.

Property	Value
required	true
type	string
examples	`Jivarus`

type[]

The type of TaxonName (e.g. Protonym, Combination).

Property	Value
required	false
type	string array
examples	`Combination&type[]=Protonym`

valid

Filter by validity. True if only valid, false if only invalid, nil if both

Property	Value
required	false
type	string \| nil
examples	`true`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Possible Responses

200

/autocomplete get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names/autocomplete?exact=true&no_leaves=true&nomenclature_group[]=Genus&nomenclature_group[]=Species&project_id=1&term=Jivarus&type[]=Combination&type[]=Protonym&valid=true&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE BODY

Example

[
  {
    "id": 11877,
    "valid_taxon_name_id": 11877,
    "label": "Jivarus Giglio-Tos, 1898",
    "label_html": "\u003cspan class=\"klass\"\u003e\u003ci\u003e\u003cmark\u003eJivarus\u003c/mark\u003e\u003c/i\u003e Giglio-Tos, 1898\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-info feedback-thin\"\u003egenus\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-secondary feedback-thin\"\u003eJivarini\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-notice feedback-thin\"\u003eJivarus\u003c/span\u003e"
  },
  {
    "id": 11888,
    "valid_taxon_name_id": 11888,
    "label": "Jivarus cohni Ronderos, 1979",
    "label_html": "\u003cspan class=\"klass\"\u003e\u003ci\u003e\u003cmark\u003eJivarus\u003c/mark\u003e cohni\u003c/i\u003e Ronderos, 1979\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-info feedback-thin\"\u003especies\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-secondary feedback-thin\"\u003e\u003ci\u003eJivarus\u003c/i\u003e\u003c/span\u003e\u0026nbsp;\u003cspan class=\"feedback feedback-notice feedback-thin\"\u003eJivarus cohni\u003c/span\u003e"
  }
]

Type

array

/{id} get

GET: /taxon_names/{id}

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Possible Responses

200

/{id} get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names/{id}?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE BODY

Example

{
  "id": 123,
  "name": "schuchmanni",
  "parent_id": 105,
  "cached": "Mirhipipteryx schuchmanni",
  "cached_html": "<i>Mirhipipteryx schuchmanni</i>",
  "feminine_name": null,
  "masculine_name": null,
  "nomenclatural_code": "iczn",
  "neuter_name": null,
  "etymology": null,
  "year_of_publication": null,
  "verbatim_author": null,
  "rank": "species",
  "rank_string": "NomenclaturalRank::Iczn::SpeciesGroup::Species",
  "type": "Protonym",
  "created_by_id": 1,
  "updated_by_id": 1211,
  "project_id": 2,
  "cached_valid_taxon_name_id": 123,
  "cached_original_combination": "Mirhipipteryx schuchmanni",
  "cached_original_combination_html": "<i>Mirhipipteryx schuchmanni</i>",
  "cached_author_year": "Günther, 1994",
  "cached_secondary_homonym": "Mirhipipteryx schuchmanni",
  "cached_primary_homonym": "Mirhipipteryx schuchmanni",
  "cached_is_valid": true,
  "created_at": "2013-02-12T18:23:00.000Z",
  "updated_at": "2020-10-19T06:54:00.000Z",
  "verbatim_name": null,
  "year": 1994,
  "name_string": "Mirhipipteryx schuchmanni Günther, 1994",
  "original_combination": "<i>Mirhipipteryx schuchmanni</i> Günther, 1994"
}

Type

array

/{id}/inventory/summary get

GET: /taxon_names/{id}/inventory/summary

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

Property	Value
required	true
type	integer
examples	`123`

page

The page of summary result set to retrieve.

Property	Value
required	false
type	integer
examples	`5`

per

The number of summary per page.

Property	Value
required	false
type	integer
examples	`10`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Response Headers

Pagination-Page

Page number of result set.

Property	Value
required	true
type	integer
examples	`5`

Pagination-Per-Page

Number of summary per Page.

Property	Value
required	true
type	integer
examples	`100`

Pagination-Previous-Page

Previous page number.

Property	Value
required	true
type	integer
examples	`4`

Pagination-Next-Page

Next page number.

Property	Value
required	true
type	integer
examples	`6`

Pagination-Total

Total number of summary in result set.

Property	Value
required	true
type	integer
examples	`30034`

Pagination-Total-Pages

Total number of pages for result set.

Property	Value
required	true
type	integer
examples	`300`

Possible Responses

200

/{id}/inventory/summary get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names/{id}/inventory/summary?id=123&page=5&per=10&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE HEADERS

Pagination-Page: 5
Pagination-Per-Page: 100
Pagination-Previous-Page: 4
Pagination-Next-Page: 6
Pagination-Total: 30034
Pagination-Total-Pages: 300

RESPONSE BODY

Example

{
  "id": 123,
  "parent_id": 105,
  "name": "schuchmanni",
  "is_valid": true,
  "full_name": "Mirhipipteryx schuchmanni Günther, 1994",
  "nomenclatural_code": "iczn",
  "short_status": "This name is valid/accepted.",
  "status": "",
  "rank": "species",
  "author": "Günther",
  "year": 1994,
  "pages": "28, 44",
  "original_citation": "Günther, K.K. (1994) Die Tridactyloidea-Fauna Kolumbiens (Orthoptera, Caelifera). <i>Deutsche entomologische Zeitschrift</i> 41, 1–56."
}

Type

array

/{id}/inventory/summary&embed[]=depictions get

GET: /taxon_names/{id}/inventory/summary&embed[]=depictions

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id}/inventory/summary&embed[]=depictions get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names/{id}/inventory/summary&embed[]=depictions?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/{id}/inventory/summary&extend[]=name_elements get

GET: /taxon_names/{id}/inventory/summary&extend[]=name_elements

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

/{id}/inventory/summary&extend[]=name_elements get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names/{id}/inventory/summary&extend[]=name_elements?token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

/parse get

GET: /taxon_names/parse

Returns a single TaxonName instance with related data included.

Header Parameters

Authorization

API access token. Do not use with "token" query string parameter.

Property	Value
required	false
type	string
examples	`Token eUUB4dQCCWlLGzksimEqNQ`

Query Parameters

combination_id

Combination_id to restrict scope of results

Property	Value
required	false
type	boolean

query_string

String expression of name(s) to parse against.

Property	Value
required	true
type	string
examples	`Ripipteryx antennata`

token

API access token. Do not use together with the "Authorization" header.

Property	Value
required	false
type	string
examples	`eUUB4dQCCWlLGzksimEqNQ`

project_token

A project (not User) token indicating the target project. Don't use together with a user token.

Property	Value
required	false
type	string
examples	`rIO2oWS603c5W5laQ8ornn`

Possible Responses

200

/parse get

CURL EXAMPLE

curl -X GET "https://{host}/api/{version}/taxon_names/parse?query_string=Ripipteryx antennata&token=eUUB4dQCCWlLGzksimEqNQ&project_token=rIO2oWS603c5W5laQ8ornn" \
	-H "Authorization: Token eUUB4dQCCWlLGzksimEqNQ"

REQUEST HEADERS

Authorization: Token eUUB4dQCCWlLGzksimEqNQ

RESPONSE BODY

Example

{
  "data": {
    "protonyms": {
      "genus": [
        {
          "id": 146,
          "name": "Ripipteryx",
          "parent_id": 104,
          "cached": "Ripipteryx",
          "cached_is_valid": true,
          "cached_html": "<i>Ripipteryx</i>",
          "feminine_name": null,
          "masculine_name": null,
          "neuter_name": null,
          "cached_author_year": "Newman, 1834",
          "etymology": null,
          "year_of_publication": null,
          "verbatim_author": null,
          "rank": "genus",
          "rank_string": "NomenclaturalRank::Iczn::GenusGroup::Genus",
          "type": "Protonym",
          "created_by_id": 1,
          "updated_by_id": 19,
          "project_id": 2,
          "cached_valid_taxon_name_id": 146,
          "cached_original_combination": "Ripipteryx",
          "cached_original_combination_html": "<i>Ripipteryx</i>",
          "cached_secondary_homonym": null,
          "cached_primary_homonym": "Ripipteryx",
          "created_at": "2013-02-12T18:23:00.000Z",
          "updated_at": "2015-05-07T09:56:00.000Z",
          "nomenclatural_code": "iczn",
          "verbatim_name": null,
          "object_tag": "<i>Ripipteryx</i>",
          "object_label": "Ripipteryx Newman, 1834",
          "global_id": "gid://taxon-works/Protonym/146",
          "base_class": "TaxonName",
          "url_for": "http://localhost:3000/taxon_names/parse",
          "object_url": "/taxon_names/146",
          "original_combination": "<i>Ripipteryx</i> Newman, 1834"
        }
      ],
      "subgenus": [],
      "species": [
        {
          "id": 153,
          "name": "antennata",
          "parent_id": 150,
          "cached": "Ripipteryx antennata",
          "cached_is_valid": true,
          "cached_html": "<i>Ripipteryx antennata</i>",
          "feminine_name": null,
          "masculine_name": null,
          "neuter_name": null,
          "cached_author_year": "Hebard, 1924",
          "etymology": null,
          "year_of_publication": null,
          "verbatim_author": null,
          "rank": "species",
          "rank_string": "NomenclaturalRank::Iczn::SpeciesGroup::Species",
          "type": "Protonym",
          "created_by_id": 1,
          "updated_by_id": 19,
          "project_id": 2,
          "cached_valid_taxon_name_id": 153,
          "cached_original_combination": "Ripipteryx antennata",
          "cached_original_combination_html": "<i>Ripipteryx antennata</i>",
          "cached_secondary_homonym": "Ripipteryx antennata",
          "cached_primary_homonym": "Ripipteryx antennata",
          "created_at": "2013-02-12T18:23:00.000Z",
          "updated_at": "2017-11-14T12:47:00.000Z",
          "nomenclatural_code": "iczn",
          "verbatim_name": null,
          "object_tag": "<i>Ripipteryx antennata</i>",
          "object_label": "Ripipteryx antennata Hebard, 1924",
          "global_id": "gid://taxon-works/Protonym/153",
          "base_class": "TaxonName",
          "url_for": "http://localhost:3000/taxon_names/parse",
          "object_url": "/taxon_names/153",
          "original_combination": "<i>Ripipteryx antennata</i> Hebard, 1924"
        },
        {
          "id": 5148,
          "name": "antennata",
          "parent_id": 5127,
          "cached": "Trilophidia antennata",
          "cached_is_valid": false,
          "cached_html": "<i>Trilophidia antennata</i>",
          "feminine_name": null,
          "masculine_name": null,
          "neuter_name": null,
          "cached_author_year": "Krauss, 1877",
          "etymology": null,
          "year_of_publication": null,
          "verbatim_author": null,
          "rank": "species",
          "rank_string": "NomenclaturalRank::Iczn::SpeciesGroup::Species",
          "type": "Protonym",
          "created_by_id": 1,
          "updated_by_id": 1,
          "project_id": 2,
          "cached_valid_taxon_name_id": 5147,
          "cached_original_combination": "Trilophidia antennata",
          "cached_original_combination_html": "<i>Trilophidia antennata</i>",
          "cached_secondary_homonym": "Trilophidia antennata",
          "cached_primary_homonym": "Trilophidia antennata",
          "created_at": "2013-02-12T18:23:00.000Z",
          "updated_at": "2013-07-20T16:40:00.000Z",
          "nomenclatural_code": "iczn",
          "verbatim_name": null,
          "object_tag": "<i>Trilophidia antennata</i>",
          "object_label": "Trilophidia antennata Krauss, 1877",
          "global_id": "gid://taxon-works/Protonym/5148",
          "base_class": "TaxonName",
          "url_for": "http://localhost:3000/taxon_names/parse",
          "object_url": "/taxon_names/5148",
          "original_combination": "<i>Trilophidia antennata</i> Krauss, 1877"
        },
        {
          "id": 13351,
          "name": "antennata",
          "parent_id": 13350,
          "cached": "Ootua antennata",
          "cached_is_valid": true,
          "cached_html": "<i>Ootua antennata</i>",
          "feminine_name": null,
          "masculine_name": null,
          "neuter_name": null,
          "cached_author_year": "Uvarov, 1927",
          "etymology": null,
          "year_of_publication": null,
          "verbatim_author": null,
          "rank": "species",
          "rank_string": "NomenclaturalRank::Iczn::SpeciesGroup::Species",
          "type": "Protonym",
          "created_by_id": 1,
          "updated_by_id": 1,
          "project_id": 2,
          "cached_valid_taxon_name_id": 13351,
          "cached_original_combination": "Ootua antennata",
          "cached_original_combination_html": "<i>Ootua antennata</i>",
          "cached_secondary_homonym": "Ootua antennata",
          "cached_primary_homonym": "Ootua antennata",
          "created_at": "2013-02-12T18:23:00.000Z",
          "updated_at": "2013-07-20T16:40:00.000Z",
          "nomenclatural_code": "iczn",
          "verbatim_name": null,
          "object_tag": "<i>Ootua antennata</i>",
          "object_label": "Ootua antennata Uvarov, 1927",
          "global_id": "gid://taxon-works/Protonym/13351",
          "base_class": "TaxonName",
          "url_for": "http://localhost:3000/taxon_names/parse",
          "object_url": "/taxon_names/13351",
          "original_combination": "<i>Ootua antennata</i> Uvarov, 1927"
        },
      ],
      "subspecies": [],
      "variety": [],
      "form": []
    },
    "parse": {
      "author": null,
      "year": null,
      "genus": "Ripipteryx",
      "subgenus": null,
      "species": "antennata",
      "subspecies": null,
      "variety": null,
      "form": null
    },
    "unambiguous": false,
    "existing_combination_id": null
  },
  "other_matches": {
    "verbatim": [],
    "subgenus": [],
    "original": [],
    "original_combination": [
      {
        "id": 153,
        "name": "antennata",
        "parent_id": 150,
        "cached": "Ripipteryx antennata",
        "cached_is_valid": true,
        "cached_html": "<i>Ripipteryx antennata</i>",
        "feminine_name": null,
        "masculine_name": null,
        "neuter_name": null,
        "cached_author_year": "Hebard, 1924",
        "etymology": null,
        "year_of_publication": null,
        "verbatim_author": null,
        "rank": "species",
        "rank_string": "NomenclaturalRank::Iczn::SpeciesGroup::Species",
        "type": "Protonym",
        "created_by_id": 1,
        "updated_by_id": 19,
        "project_id": 2,
        "cached_valid_taxon_name_id": 153,
        "cached_original_combination": "Ripipteryx antennata",
        "cached_original_combination_html": "<i>Ripipteryx antennata</i>",
        "cached_secondary_homonym": "Ripipteryx antennata",
        "cached_primary_homonym": "Ripipteryx antennata",
        "created_at": "2013-02-12T18:23:00.000Z",
        "updated_at": "2017-11-14T12:47:00.000Z",
        "nomenclatural_code": "iczn",
        "verbatim_name": null,
        "object_tag": "<i>Ripipteryx antennata</i>",
        "object_label": "Ripipteryx antennata Hebard, 1924",
        "global_id": "gid://taxon-works/Protonym/153",
        "base_class": "TaxonName",
        "url_for": "http://localhost:3000/taxon_names/parse",
        "object_url": "/taxon_names/153",
        "original_combination": "<i>Ripipteryx antennata</i> Hebard, 1924"
      }
    ]
  }
}

Type

array