Skip to content

Files

This section describes the File-related operations in the Blockgraph API, including how to upload files and the structure of file objects.

The File Object

The File object represents a file that has been uploaded to the Blockgraph platform.

Upload a File

Uploads a file for a specific feature and signal type.

Endpoint

POST /api/files

Headers

  • Content-Type: multipart/form-data
  • Accept: application/vnd.blockgraph.v1+json
  • Authorization: Bearer {access-token}

Query Parameters

Name Type Required Description
featureType string false The type of feature the file is associated with. Default: SEGMENT_UPLOAD
uploadSignal string true The type of signal
resultContent string true Type of content in the result

Enumerated Values for Parameters

Parameter Possible Values
featureType SEGMENT_UPLOAD
uploadSignal IP, IDFA, AAID, STBID, EMAIL, ADDRESS, PARTNER_RECORD_ID, BGID, RECORD_ID
resultContent BGID, HASHED

Request Body

The request body should be multipart/form-data with the following part:

Name Type Required Description
file file true The file to be uploaded (maximum size: 150 MB)

File Size Limit

The maximum allowed file size for upload is 150 MB. Attempts to upload files larger than this limit will result in an error.

Example Request

curl -X POST "https://api.{participant id}.blockgraph.app/api/files?uploadSignal=IP&resultContent=BGID" \
  -H "Content-Type: multipart/form-data" \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token" \
  -F "file=@/path/to/segments_file.csv"

Responses

Status Meaning Description
200 OK Successful file upload
400 Bad Request Invalid request parameters or file
500 Internal Server Error Server-side error

Example Success Response (200 OK)

{
  "name": "segments_file.csv"
}

Retrieve Files

Retrieves files based on feature type and signal type.

Endpoint

GET /api/files

Headers

  • Accept: application/vnd.blockgraph.v1+json
  • Authorization: Bearer {access-token}

Query Parameters

Name Type Required Description
featureType string false The type of feature to filter files by. Default: SEGMENT_UPLOAD
uploadSignal string true The type of signal to filter files by
resultContent string true Type of content in the result to filter files by

Enumerated Values for Parameters

Parameter Possible Values
featureType SEGMENT_UPLOAD
uploadSignal IP, IDFA, AAID, STBID, EMAIL, ADDRESS, PARTNER_RECORD_ID, BGID, RECORD_ID
resultContent BGID, HASHED

Example Request

curl -X GET "https://api.{participant id}.blockgraph.app/api/files?uploadSignal=IP&resultContent=BGID" \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token"

Responses

Status Meaning Description
200 OK A list of files matching the specified criteria
400 Bad Request Invalid request parameters
500 Internal Server Error Server-side error

Example Success Response (200 OK)

{
  "files": [
    {
      "name": "segments_file1.csv"
    },
    {
      "name": "segments_file2.csv"
    }
  ],
  "page": 0,
  "pageSize": 10,
  "hasMore": false
}

Delete a File

Deletes a file by its name, feature type, and signal type.

Endpoint

DELETE /api/files/{file}

Headers

  • Accept: application/vnd.blockgraph.v1+json
  • Authorization: Bearer {access-token}

Path Parameters

Name Type Required Description
file string true The name of the file to be deleted

Query Parameters

Name Type Required Description
featureType string false The type of feature the file is associated with. Default: SEGMENT_UPLOAD
uploadSignal string true The type of signal the file is associated with
resultContent string true Type of content in the result the file is associated with

Enumerated Values for Parameters

Parameter Possible Values
featureType SEGMENT_UPLOAD
uploadSignal IP, IDFA, AAID, STBID, EMAIL, ADDRESS, PARTNER_RECORD_ID, BGID, RECORD_ID
resultContent BGID, HASHED

Example Request

curl -X DELETE "https://api.{participant id}.blockgraph.app/api/files/segments_file.csv?uploadSignal=IP&resultContent=BGID" \
  -H "Accept: application/vnd.blockgraph.v1+json" \
  -H "Authorization: Bearer $access_token"

Responses

Status Meaning Description
200 OK File successfully deleted
400 Bad Request Invalid request parameters
404 Not Found File not found
500 Internal Server Error Server-side error