# Apply a bulk action to observations

POST /observations/bulk. Parameters, permissions, request and response schemas.

`POST /observations/bulk`

Apply a bulk action to observations. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.

## Authentication

Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication).

```json
{
  "ability": "write",
  "team": "Token-bound Team",
  "authorization": "Additional role, entity-policy and plan requirements vary by operation.",
  "billing": "Blocked billing mode rejects writes with 402."
}
```

## Request body

A request body is required.

### application/json

```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "accept",
        "dismiss",
        "restore-dismissal",
        "archive",
        "delete",
        "duplicate"
      ]
    },
    "ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "minItems": 1
    }
  },
  "required": [
    "action",
    "ids"
  ],
  "title": "BulkObservationActionRequest"
}
```

```json
{
  "action": "accept",
  "ids": [
    1
  ]
}
```

## Example request

```bash
curl --request POST 'https://api.example.test/api/observations/bulk' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"action":"accept","ids":[1]}'
```

Examples use fictional data. Replace resource IDs and the API host with your environment’s values.

## Responses

### 200

Array of `ObservationResource`

Content type: `application/json`.

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "const": "delete"
        },
        "count": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "action",
        "count"
      ]
    },
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "const": "archive"
        },
        "count": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "action",
        "count"
      ]
    },
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "description": "The bulk action from the request."
        },
        "count": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "action",
        "count"
      ]
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "project_id": {
                "type": "integer"
              },
              "research_collection_id": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "user_id": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_type": {
                "type": "string"
              },
              "source_id": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "source_item_key": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_label": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "evidence_kind": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "evidence_payload": {
                "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.",
                "anyOf": [
                  {
                    "type": "object",
                    "additionalProperties": {
                      "description": "An arbitrary JSON value retained by a metadata/settings field.",
                      "oneOf": [
                        {
                          "type": "null"
                        },
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "string"
                        },
                        {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/JsonValue"
                          }
                        },
                        {
                          "type": "object",
                          "additionalProperties": {
                            "$ref": "#/components/schemas/JsonValue"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "type": "array",
                    "items": {
                      "description": "An arbitrary JSON value retained by a metadata/settings field.",
                      "oneOf": [
                        {
                          "type": "null"
                        },
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "string"
                        },
                        {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/JsonValue"
                          }
                        },
                        {
                          "type": "object",
                          "additionalProperties": {
                            "$ref": "#/components/schemas/JsonValue"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "confidence": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "observed_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "locked": {
                "type": "boolean"
              },
              "accepted_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "accepted_by": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "dismissed_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "dismissed_by": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "created_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "deleted_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "review_status": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "project_id",
              "research_collection_id",
              "user_id",
              "name",
              "description",
              "source_type",
              "source_id",
              "source_item_key",
              "source_label",
              "evidence_kind",
              "evidence_payload",
              "confidence",
              "observed_at",
              "locked",
              "accepted_at",
              "accepted_by",
              "dismissed_at",
              "dismissed_by",
              "created_at",
              "updated_at",
              "deleted_at",
              "review_status"
            ],
            "title": "ObservationResource"
          }
        }
      },
      "required": [
        "data"
      ]
    }
  ]
}
```

```json
{
  "action": "delete",
  "count": 1
}
```

### 401

Unauthenticated

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error overview."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "The request could not be completed."
}
```

### 402

The Team is in read-only billing mode.

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "const": "subscription_required"
    },
    "mode": {
      "type": "string",
      "const": "blocked"
    },
    "message": {
      "type": "string",
      "example": "Your team is in read-only mode. Update billing to make changes."
    },
    "grace_period_ends_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  },
  "required": [
    "error",
    "mode",
    "message",
    "grace_period_ends_at"
  ]
}
```

```json
{
  "error": "subscription_required",
  "mode": "blocked",
  "message": "Your team is in read-only mode. Update billing to make changes.",
  "grace_period_ends_at": null
}
```

### 403

Authorization error

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error overview."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "The request could not be completed."
}
```

### 422

Validation error

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Errors overview."
    },
    "errors": {
      "type": "object",
      "description": "A detailed description of each field that failed validation.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "message",
    "errors"
  ]
}
```

```json
{
  "message": "The request could not be completed.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}
```

### 429

Rate limit exceeded. Honor Retry-After before retrying.

Response headers:

```json
{
  "Retry-After": {
    "description": "Seconds before retrying.",
    "schema": {
      "type": "integer"
    }
  }
}
```

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "Too Many Attempts."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "Too Many Attempts."
}
```

See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads.