openapi: 3.2.0 info: title: Lucid Data Data Item API version: '1.0' description: The Lucid Data API enables external applications to create, read, update, and delete structured data linked to Lucid documents. Use it to sync data sets, collections, and schemas between your data sources and Lucid diagrams. Authenticate via OAuth 2.0. contact: name: Lucid Developer Platform url: https://developer.lucid.co/ x-documentation: https://developer.lucid.co/reference/data-api servers: - url: https://data.lucid.app tags: - name: Data Item description: Create, retrieve, update, and delete individual data items within a collection. A data item is a single record conforming to the collection's schema. paths: /collections/{collectionId}/items: head: summary: Get Total Data Items Count description: 'This endpoint returns the number of data items a user has access to. The return value is in the response headers as Lucid-Items-Total ' operationId: getTotalDataItemsCount tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to get total data items count for required: true schema: type: integer responses: '200': description: OK headers: Lucid-Items-Total: description: Total number of data items in the collection schema: type: integer example: 17 get: summary: Get All Data Items description: 'This endpoint returns all data items within a collection that the user has access to. The results will be paginated. If the number of data items exceeds the pagination limit, links will be provided to get the next set of results or the previous set of results (if applicable). The range of returned values can be determined by optional start and end parameters. If the difference between the end and start values is greater than the pagination limit, the endpoint returns collections in the range from start to start + pagination limit. Items in the response are determined based on their creation order. This endpoint also supports an optional filter string that can be used to filter down the data items returned based off the items'' fields'' values. If a filter is included, the start and end parameters only refer to items which satisfy the filter; this is also true of the total value in the response. For more details, see Data Item Filters. ' operationId: getAllDataItems tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to get data items from required: true schema: type: integer - name: start in: query description: Starting 1-based index of the data items to return. Defaults to 1. required: false schema: type: integer example: 1 - name: end in: query description: Ending 1-based index of the data items to return. Defaults to 10000. required: false schema: type: integer example: 100 - name: filter in: query description: URL encoded filter string. Example unencoded is `filter=age > 16` required: false schema: type: string example: filter=age%20%3E%2016 responses: '200': description: OK with paginated list of Data Items content: application/json: schema: type: object properties: items: type: array description: List of data items items: type: object properties: uri: type: string description: Link to self example: https://data.lucid.app/collections/2/items/4 collection: type: string description: Link to the collection the item belongs to example: https://data.lucid.app/collections/2 fields: type: object description: Mapping of field names found in schema to this specific item's values example: Co1B: value1 Co2B: value2 required: - uri - collection - fields example: uri: https://data.lucid.app/collections/2/items/4 collection: https://data.lucid.app/collections/2 fields: Co1B: value1 Co2B: value2 total: type: integer description: Total number of data items in the collection example: 175 prev: type: string description: Link to get the previous set of data items example: https://data.lucid.app/collections/2/items?start=1&end=100 next: type: string description: Link to get the next set of data items example: https://data.lucid.app/collections/2/items?start=201&end=300 post: summary: Create Data Items description: 'If the user has access to the collection, new data items are created using the supplied values. Primary key constraints are not enforced. Any field name that is not part of the schema definition is ignored by default. The schema should be created prior to any data items being created. ' operationId: createDataItems tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to create data items for required: true schema: type: integer requestBody: required: true content: application/json: schema: type: array description: Field value pairs to create data items from. Each mapping is for a single data item items: type: object additionalProperties: type: string example: Co1B: value1 Co2B: value2 responses: '200': description: OK with Array[Data Item] containing the newly created data items content: application/json: schema: type: array items: type: object properties: uri: type: string description: Link to self example: https://data.lucid.app/collections/2/items/4 collection: type: string description: Link to the collection the item belongs to example: https://data.lucid.app/collections/2 fields: type: object description: Mapping of field names found in schema to this specific item's values example: Co1B: value1 Co2B: value2 required: - uri - collection - fields example: uri: https://data.lucid.app/collections/2/items/4 collection: https://data.lucid.app/collections/2 fields: Co1B: value1 Co2B: value2 patch: summary: Update Data Items description: 'This endpoint allows updating multiple data items at once. The easiest way to accomplish is to modify the values in the response from Get All Data Items and send a PATCH request. Changing the values will update existing data item values. The collection field is ignored as the data item cannot be moved to a different collection. It the new value is null, it means the value is deleted. If the provided field name does not exist in the collection schema, that value is ignored. ' operationId: updateDataItems tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to update data items for required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: uri: type: string description: URI of data item to be updated example: https://data.lucid.app/collections/2/items/4 fields: type: object description: Field value pairs to update data items from. Mapping is for a single data item example: Co1B: new column 1b value Co2B: new column 2b value required: - uri - fields example: uri: https://data.lucid.app/collections/2/items/4 fields: Co1B: new column 1b value Co2B: new column 2b value responses: '200': description: OK with Array[Data Item] containing the updated data items content: application/json: schema: type: array items: type: object properties: uri: type: string description: Link to self example: https://data.lucid.app/collections/2/items/4 collection: type: string description: Link to the collection the item belongs to example: https://data.lucid.app/collections/2 fields: type: object description: Mapping of field names found in schema to this specific item's values example: Co1B: value1 Co2B: value2 required: - uri - collection - fields example: uri: https://data.lucid.app/collections/2/items/4 collection: https://data.lucid.app/collections/2 fields: Co1B: value1 Co2B: value2 delete: summary: Delete Data Items description: 'Removes only the data items provided in the query parameter. The data items in the query parameter must belong to the collection specified. The deletion cannot be undone. The deletion will only occur if the user has access to the data source. ' operationId: deleteDataItems tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to delete data items from required: true schema: type: integer - name: items in: query description: List of data item URI's to remove from specified collection required: true schema: type: array items: type: string responses: '200': description: OK /collections/{collectionId}/items/{dataItemId}: get: summary: Get Data Item description: 'Gets a specific existing data item from a given collection ' operationId: getDataItem tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to get data item from required: true schema: type: integer - name: dataItemId in: path description: ID of data item to get required: true schema: type: integer responses: '200': description: OK with Data Item content: application/json: schema: type: object properties: uri: type: string description: Link to self example: https://data.lucid.app/collections/2/items/4 collection: type: string description: Link to the collection the item belongs to example: https://data.lucid.app/collections/2 fields: type: object description: Mapping of field names found in schema to this specific item's values example: Co1B: value1 Co2B: value2 required: - uri - collection - fields example: uri: https://data.lucid.app/collections/2/items/4 collection: https://data.lucid.app/collections/2 fields: Co1B: value1 Co2B: value2 post: summary: Get Data Items By Key description: 'Returns all data items in the specified collection whose field values match the values specified in a Data Item By Key Find JSON Object. If necessary, you can paginate this endpoint''s results using query parameters. Note: For more complex data item search queries, consider using the filter parameter with Get All Data Items. ' operationId: getDataItemsByKey tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to get data items from required: true schema: type: integer - name: dataItemId in: path description: ID of data item to get required: true schema: type: integer - name: start in: query description: Starting 1-based index of the data items to return. Defaults to 1. required: false schema: type: integer example: 1 - name: end in: query description: Ending 1-based index of the data items to return. Defaults to 10000. required: false schema: type: integer example: 100 requestBody: required: true content: application/json: schema: type: object properties: targetValues: type: array description: List of parameters by which to search for data items items: type: object properties: fieldValues: type: array description: Specifies the actual value that the fields need to have to be found items: type: string example: Ontario keySchemaFields: type: array description: Fields used to search for items in the collection. If it is not provided, primary keys from the schema are used. items: type: string example: Province required: - targetValues example: targetValues: - fieldValues: - Ontario keySchemaFields: - Province responses: '200': description: OK with paginated list of Data Items content: application/json: schema: type: object properties: items: type: array description: List of data items items: type: object properties: uri: type: string description: Link to self example: https://data.lucid.app/collections/2/items/4 collection: type: string description: Link to the collection the item belongs to example: https://data.lucid.app/collections/2 fields: type: object description: Mapping of field names found in schema to this specific item's values example: Co1B: value1 Co2B: value2 required: - uri - collection - fields example: uri: https://data.lucid.app/collections/2/items/4 collection: https://data.lucid.app/collections/2 fields: Co1B: value1 Co2B: value2 total: type: integer description: Total number of data items in the collection example: 175 prev: type: string description: Link to get the previous set of data items example: https://data.lucid.app/collections/2/items?start=1&end=100 next: type: string description: Link to get the next set of data items example: https://data.lucid.app/collections/2/items?start=201&end=300 patch: summary: Update Data Item description: 'Update values for the specified item. The easiest way to accomplish is to modify the values in the response from Get Data Item and send a PATCH request. Changing the values will update existing data item values. The collection field is ignored as the data item cannot be moved to a different collection. It the new value is null, it means the value is deleted. If the provided field name does not exist in the collection schema, that value is ignored. ' operationId: updateDataItem tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to update data item for required: true schema: type: integer - name: dataItemId in: path description: ID of data item to update required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: uri: type: string description: URI of data item to be updated example: https://data.lucid.app/collections/2/items/4 fields: type: object description: Field value pairs to update data items from. Mapping is for a single data item example: Co1B: new column 1b value Co2B: new column 2b value required: - uri - fields example: uri: https://data.lucid.app/collections/2/items/4 fields: Co1B: new column 1b value Co2B: new column 2b value responses: '200': description: OK with Data Item content: application/json: schema: type: object properties: uri: type: string description: Link to self example: https://data.lucid.app/collections/2/items/4 collection: type: string description: Link to the collection the item belongs to example: https://data.lucid.app/collections/2 fields: type: object description: Mapping of field names found in schema to this specific item's values example: Co1B: value1 Co2B: value2 required: - uri - collection - fields example: uri: https://data.lucid.app/collections/2/items/4 collection: https://data.lucid.app/collections/2 fields: Co1B: value1 Co2B: value2 delete: summary: Delete Data Item description: 'Removes the specified data item from the collection. This deletion cannot be undone. The deletion will only occur if the user has access to the data source. ' operationId: deleteDataItem tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to delete data item from required: true schema: type: integer - name: dataItemId in: path description: ID of data item to delete required: true schema: type: integer responses: '200': description: OK /collections/{collectionId}/itemsByKey: patch: summary: Update Data Items By Key description: 'Find any data items whose fields match specified values and update those items using a patch. If the value of a field in a patch is null, that value will be deleted from the item. If the provided field name does not exist in the collection schema, that value is ignored. Attempts to update the Collection field will be ignored as a data item cannot be moved to a different collection. ' operationId: updateDataItemsByKey tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to update data items for required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: patches: type: array description: Define what items from the collection you are changing and how to change them. The order of strings in fieldValues must match that of either keySchemaFields or of the actual primary keys from the real schema if keySchemaFields is not defined. items: type: object properties: fieldValues: type: array description: Specifies the actual value that the fields need to have to be found items: type: string example: Ontario patch: type: object description: List of field names with the new value that the field should be set to. Changes will be applied to any matching items and if the value is null, that field will be deleted from the matching data items. example: Co1B: new column 1b value Co2B: new column 2b value keySchemaFields: type: array description: Fields used to search for items in the collection. If it is not provided, primary keys from the schema are used. items: type: string example: Province required: - patches example: patches: - fieldValues: - Ontario patch: Co1B: new column 1b value Co2B: new column 2b value keySchemaFields: - Province responses: '200': description: OK with message indicating the number of items updated. content: application/json: schema: type: object properties: message: type: string description: Message indicating the number of items updated example: Updated 5 item(s) delete: summary: Delete Data Items By Key description: 'Finds all the items whose key values match those specified by the payload and deletes them. The deletion cannot be undone. The deletion will only occur if the user has access to the data source. ' operationId: deleteDataItemsByKey tags: - Data Item security: - OAuth2: - data-service.admin parameters: - name: collectionId in: path description: ID of collection to delete data items from required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: targetValues: type: array description: Defines what items within the collection you are searching for. The order of strings in fieldValues must match that of either keySchemaFields or of the actual primary keys from the real schema if keySchemaFields is not defined. items: type: object properties: fieldValues: type: array description: Specifies the actual value that the fields need to have to be found items: type: string example: Ontario keySchemaFields: type: array description: Fields used to search for items in the collection. If it is not provided, primary keys from the schema are used. items: type: string example: Province required: - targetValues example: targetValues: - fieldValues: - Joey - Ontario keySchemaFields: - first name - last name responses: '200': description: OK components: securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://lucid.app/oauth2/authorize tokenUrl: https://api.lucid.co/oauth2/token refreshUrl: https://api.lucid.co/oauth2/token scopes: data-service.admin: Scope needed for access to the Data APIs. x-harvest: harvested: '2026-08-01' method: searched source: https://lucid-developer-docs.readme.io/mcp note: 'Assembled operation-by-operation from Lucid''s own documentation MCP server (tools list-endpoints + get-endpoint), which returns verbatim OpenAPI 3.0.3 fragments out of the spec Lucid uploaded to its ReadMe hub (/branches/1.4/apis/lucid-data-api.json). Paths, operations, parameters, request bodies, responses, components and securitySchemes are provider content, unmodified. Only the info block is ours: ReadMe''s per-endpoint fragments omit info, so title/description are copied verbatim from the provider''s own list-specs description for this spec.'