Pets API

Ask about this page View Markdown

Base URL: https://YOUR-SERVER/api. Send your API key in x-api-key where authentication is required. A key also needs the listed permission; your account's access rules still apply.

API guide · All endpoints · OpenAPI JSON

GET /pets — Retrieve pets
POST /pets — Create a pet
POST /pets/candidates/{id}/accept — Accept a pet recognition candidate
POST /pets/candidates/{id}/reject — Reject a pet recognition candidate
GET /pets/observations — Retrieve the pet observations of an asset
DELETE /pets/observations/{id} — Remove a pet observation
DELETE /pets/{id} — Delete a pet
GET /pets/{id} — Retrieve a pet
PUT /pets/{id} — Update a pet
POST /pets/{id}/merge — Merge pets
GET /pets/{id}/observations — Retrieve pet observations
POST /pets/{id}/observations — Add a pet observation

Retrieve pets

GET /api/pets

Retrieve the signed-in account’s pet identities.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`withHidden`	query	No	Include hidden pets

Parameter types, defaults and constraints

[
  {
    "name": "withHidden",
    "required": false,
    "in": "query",
    "description": "Include hidden pets",
    "schema": {
      "type": "boolean"
    }
  }
]

Responses

Field definitions: PetResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/PetResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Create a pet

POST /api/pets

Create a durable pet identity with a name, species and optional birthday.

Authentication: API key. Permission: all.

Request body

Required.

Field definitions: PetCreateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PetCreateDto"
    }
  }
}

Responses

Field definitions: PetResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PetResponseDto"
        }
      }
    },
    "description": ""
  }
}

Accept a pet recognition candidate

POST /api/pets/candidates/{id}/accept

Record a durable confirmed observation for the proposed pet, or for a different pet when one is supplied.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: PetCandidateReviewDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PetCandidateReviewDto"
    }
  }
}

Responses

Field definitions: PetObservationResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PetObservationResponseDto"
        }
      }
    },
    "description": ""
  }
}

Reject a pet recognition candidate

POST /api/pets/candidates/{id}/reject

Record a durable rejection so the proposal does not return after the model is rerun.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: PetCandidateRejectDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PetCandidateRejectDto"
    }
  }
}

Responses

Field definitions: PetObservationResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PetObservationResponseDto"
        }
      }
    },
    "description": ""
  }
}

Retrieve the pet observations of an asset

GET /api/pets/observations

Retrieve the signed-in account’s decisions about which of its pets appear in one asset.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`assetId`	query	Yes	Asset whose pet observations to list

Parameter types, defaults and constraints

[
  {
    "name": "assetId",
    "required": true,
    "in": "query",
    "description": "Asset whose pet observations to list",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: PetObservationResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/PetObservationResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Remove a pet observation

DELETE /api/pets/observations/{id}

Undo a durable observation, whether it was drawn by hand or made in review. With `expectedChecksum`, refused with 409 when the original changed.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`expectedChecksum`	query	No	Checksum of the original the decision was made on (base64); refused with 409 when it changed
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "expectedChecksum",
    "required": false,
    "in": "query",
    "description": "Checksum of the original the decision was made on (base64); refused with 409 when it changed",
    "schema": {
      "minLength": 1,
      "maxLength": 200,
      "type": "string"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

{
  "204": {
    "description": ""
  }
}

Delete a pet

DELETE /api/pets/{id}

Delete a pet identity and every observation recorded for it.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

{
  "204": {
    "description": ""
  }
}

Retrieve a pet

GET /api/pets/{id}

Retrieve a single pet identity.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: PetResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PetResponseDto"
        }
      }
    },
    "description": ""
  }
}

Update a pet

PUT /api/pets/{id}

Update a pet’s name, species, birthday, featured photo, hidden or favorite state.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: PetUpdateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PetUpdateDto"
    }
  }
}

Responses

Field definitions: PetResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PetResponseDto"
        }
      }
    },
    "description": ""
  }
}

Merge pets

POST /api/pets/{id}/merge

Merge other pet identities into this one, keeping every durable observation.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: PetMergeDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PetMergeDto"
    }
  }
}

Responses

Field definitions: PetResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PetResponseDto"
        }
      }
    },
    "description": ""
  }
}

Retrieve pet observations

GET /api/pets/{id}/observations

Retrieve the durable observations recorded for a pet.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: PetObservationResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/PetObservationResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Add a pet observation

POST /api/pets/{id}/observations

Record by hand that a pet appears in an asset, optionally with a drawn region.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: PetObservationCreateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PetObservationCreateDto"
    }
  }
}

Responses

Field definitions: PetObservationResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PetObservationResponseDto"
        }
      }
    },
    "description": ""
  }
}

Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.