> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmetal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a Data Entity

> This endpoint creates a new Data Entity.

### Two-step process

This endpoint is a two-step process. First, you create the data entity's URL, and then you upload the file to the signed URL.

* Step 1: `POST https://api.getmetal.io/v1/data-entities`
* Step 2: `PUT` to the signed URL

## Step 1: Request URL for the File

### Auth Headers

<ParamField required header="x-metal-api-key" type="string">
  An API key for your org.
</ParamField>

<ParamField required header="x-metal-client-id" type="string">
  A Client ID for your org.
</ParamField>

### Body

<ParamField required body="datasource" type="ObjectID" placeholder="Datasource ObjectID">
  The datasource ID.
</ParamField>

<ParamField required body="name" type="string" placeholder="Entity Name">
  The name of the data entity.
</ParamField>

<ParamField optional body="metadata" type="object">
  An object of metdatadata keys/values. The key is the field key and the value
  is the field value for this entity.
</ParamField>

<ParamField required body="sourceType" type="string" placeholder="Source Type">
  The type of the source (e.g., "PDF", "Text").
</ParamField>

### Response

<ResponseField name="data" type="Data Entity Object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      The unique identifier of the data entity.
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the data entity.
    </ResponseField>

    <ResponseField name="createdBy" type="string">
      The user ID who created this entity.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp indicating when the data entity was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash theme={null}
  # Example Request
  curl -X POST "https://api.getmetal.io/v1/data-entities" \
  --header 'Content-Type: application/json' \
  --header 'x-metal-api-key: <api-key>' \
  --header 'x-metal-client-id: <client-id>' \
  --data '{
    "datasource": "datasourceID",
    "name": "Song Lyrics",
    "sourceType": "file",
    "metadata": {
      "author": "Rolling Stone"
    }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "id": "dataEntityID",
      "datasource": "datasourceID",
      "name": "Song Lyrics",
      "extractedMetadata": [
        {
          "name": "band",
          "value": "Iron Maiden",
          "type": "string",
          "autoExtract": true
        }
      ],
      "sourcetype": "file",
      "status": "CREATED",
      "createdAt": "2023-08-29T17:00:55.002Z",
      "updatedAt": "1970-01-01T00:00:00Z",
      "metadata": {
        "author": "Rolling Stone",
        "band": "Iron Maiden"
      },
      "metadataFields": [
        {
          "name": "band",
          "type": "string",
          "description": "Which heavy metal band is represented by the iconic mascot Eddie?",
          "autoExtract": true
        },
        {
          "name": "author",
          "type": "string",
          "autoExtract": false
        }
      ],
      "url": "signed_upload_url",
      "createdBy": "userID"
    }
  }
  ```
</ResponseExample>

## Step 2: Upload the File to the Signed URL

```bash theme={null}
# Example Request
curl --location --request PUT '<preSignedUrl>' \
--header 'Content-Type: application/pdf' \
--upload-file '/path/to/your/example.pdf'
```