> ## Documentation Index > Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a data request > Creates a data request. A request with recipients and no schedule is emailed to them as soon as it is created, and `sent_at` is set. Pass `schedule_attributes` to send it later instead: a one-off schedule sends it once at `next_execution_at`, and a `recurrence_rule` makes it a template that sends a copy on each run. Requires the `read:project` and `write:data_request` token scopes. ## OpenAPI ````yaml POST /projects/{project_id}/data_requests openapi: 3.1.0 info: title: Mangrove - API version: 1.1.0 description: > ## Filtering and sorting List endpoints that accept `filter` take one query parameter per condition, written `filter[field][comparator]=value`, for example `filter[name][contains]=North`. The comparators are `eq`, `neq`, `gt`, `geq`, `lt`, `leq` and `contains`, and `filter[field]=value` is short for `eq`. Conditions combine with AND. `contains` matches part of the value, is case-sensitive, and applies only to text fields. An unknown field or comparator, a value that doesn't fit the field's type, or a list or object as the value returns 400 with a message naming the problem. Each list operation names its filterable fields; some take only `eq`, and say so. `sort` takes a comma-separated list of fields, for example `sort=-created_at,name`. Each field sorts ascending, or descending with a `-` prefix. Unknown sort fields are ignored. Sorting by `id` orders by the record's internal ID, not its friendly ID. Each list operation names its sortable fields. servers: - url: https://app.gomangrove.com/api/v1 security: - sec0: [] paths: /projects/{project_id}/data_requests: parameters: - $ref: '#/components/parameters/ProjectId' post: summary: Create a data request description: > Creates a data request. A request with recipients and no schedule is emailed to them as soon as it is created, and `sent_at` is set. Pass `schedule_attributes` to send it later instead: a one-off schedule sends it once at `next_execution_at`, and a `recurrence_rule` makes it a template that sends a copy on each run. Requires the `read:project` and `write:data_request` token scopes. operationId: create-data-request requestBody: required: true content: application/json: schema: type: object required: - data_request properties: data_request: allOf: - $ref: '#/components/schemas/DataRequestInput' required: - inputs_attributes properties: inputs_attributes: minItems: 1 example: data_request: name: Monthly fuel use start_time: '2026-03-01T00:00:00Z' end_time: '2026-04-01T00:00:00Z' message: Please upload last month's fuel records. inputs_attributes: - nexus_event_type_id: 101 recipients_attributes: - email: operator@example.com recipient_type: to responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/DataRequest' '400': $ref: '#/components/responses/MissingParameter' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': description: >- Validation failed, including errors on the schedule (reported on the `schedule` field) and a recipient user outside your account, or the project has no nexus config content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingTimes: value: errors: - message: Start time can't be blank field: start_time code: blank recipientOutsideAccount: value: errors: - message: Recipient user is not a member of this account noDataConfiguration: value: errors: - message: Project does not have Nexus configuration components: parameters: ProjectId: name: project_id in: path required: true description: The project's friendly ID (e.g. `prj_aBcD1234eFgH5678`). schema: type: string schemas: DataRequestInput: type: object description: > `start_time` and `end_time` are required unless the request is a template (it has a recurring schedule). A request needs at least one entry in `inputs_attributes`. properties: name: type: string start_time: type: string format: date-time end_time: type: string format: date-time message: type: string inputs_attributes: type: array description: The event types to request data for, one entry each. items: type: object properties: id: type: integer description: Numeric ID of an existing input, to update or remove it nexus_event_type_id: type: integer description: >- Numeric event type ID. Required for a new input; an event type can appear once per request, and an archived one is rejected. _destroy: type: boolean recipients_attributes: type: array items: type: object description: Give either `user_id` or `email`, not both. properties: id: type: integer description: Numeric ID of an existing recipient, to update or remove it user_id: type: integer description: >- Numeric ID of a user in your account. Any other user returns 422 "Recipient user is not a member of this account". email: type: string format: email recipient_type: type: string enum: - to - cc default: to _destroy: type: boolean schedule_attributes: allOf: - $ref: '#/components/schemas/ScheduleInput' description: >- Attaches a schedule, or updates the attached one. A `recurrence_rule` makes the request a template. On update, `_destroy` set to true cancels the schedule. properties: _destroy: type: boolean DataRequest: type: object properties: id: type: string example: req_AaBbCcDdEeFfGgHh name: type: - string - 'null' role: type: string enum: - sendable - template description: >- `template` for a request with a recurring schedule, which sends a copy on each run; otherwise `sendable`. start_time: type: - string - 'null' format: date-time end_time: type: - string - 'null' format: date-time sent_at: type: - string - 'null' format: date-time description: When the request email was first sent, or null. message: type: - string - 'null' url: type: string format: uri description: >- The submission link sent to recipients. Anyone holding it can submit data without signing in, so treat it as a secret. example: https://app.gomangrove.com/nexus/data_requests/SIGNED_ID template_id: type: - string - 'null' description: The friendly ID of the template this request was sent from, if any. example: req_AaBbCcDdEeFfGgHh recurring_schedule_friendly_id: type: - string - 'null' description: >- The friendly ID of the recurring schedule that sent this request, if any. schedule: description: The attached schedule, or null when there is none. anyOf: - $ref: '#/components/schemas/Schedule' - type: 'null' created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object required: - errors properties: errors: type: array items: type: object required: - message properties: message: type: string description: Human-readable error message field: type: string description: Attribute the error applies to (validation errors only) code: type: string description: Machine-readable error code (validation errors only) blocking: type: array description: >- Bounded preview of the records blocking a destroy (blocked-destroy errors only) items: $ref: '#/components/schemas/DeletionBlockingRecord' blocking_count: type: integer description: >- Total count of records blocking a destroy (blocked-destroy errors only) config_key: type: string description: >- The data feed source config setting to fix, when the error is on `config` (data feed source validation errors only) count: type: number description: >- The limit or comparison value the failed validation checked against, e.g. a maximum length or a numeric bound (validation errors only, when the validation has one) value: description: >- The rejected value, e.g. on an inclusion or uniqueness failure (validation errors only, when the validation reports one) ScheduleInput: type: object properties: next_execution_at: type: string format: date-time description: When the next send happens. Required on create; optional on update. end_condition: type: string enum: - never - on_date - after_count description: >- Defaults to `never`. On create, a one-off schedule (no `recurrence_rule`) is set to `after_count` whatever is sent; a later update can change it. end_date: type: string format: date description: >- Required when `end_condition` is `on_date`; must be on or after the date of `next_execution_at` in the account's time zone. max_occurrences: type: integer minimum: 1 description: >- Required when `end_condition` is `after_count`. Defaults to 1 on a one-off schedule. recurrence_rule: type: object description: Omit for a one-off schedule. required: - type - interval properties: type: type: string enum: - daily - weekly - monthly interval: type: integer minimum: 1 Schedule: type: object properties: id: type: string example: sch_AaBbCcDdEeFfGgHh status: type: string enum: - active - paused - completed description: '`completed` once the schedule has finished or been cancelled.' recurrence_rule: type: - object - 'null' description: Null for one-off schedules. properties: type: type: string enum: - daily - weekly - monthly interval: type: integer minimum: 1 starts_at: type: - string - 'null' format: date-time description: The first `next_execution_at` the schedule was created with. next_execution_at: type: - string - 'null' format: date-time description: Null once the schedule is completed. last_executed_at: type: - string - 'null' format: date-time end_condition: type: string enum: - never - on_date - after_count end_date: type: - string - 'null' format: date max_occurrences: type: - integer - 'null' execution_count: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time DeletionBlockingRecord: type: object required: - type properties: type: type: string friendly_id: type: string name: type: - string - 'null' description: >- Display label, and the only identifier for records that have no friendly_id responses: MissingParameter: description: >- A required parameter or body object is missing or empty. The message names it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - message: 'param is missing or the value is empty or invalid: project' Unauthorized: description: >- The API token is missing, invalid or expired. The body is empty, except for an expired token, which returns the error below. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - message: API token has expired Forbidden: description: >- The token lacks the scope the operation's description names, or a condition the description states applies, such as a feature that isn't enabled for your account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - message: You are not authorized to perform this action NotFound: description: >- A resource named in the path doesn't exist in your account, or the token can't see it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - message: Record not found securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: '' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.