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

# Create Blob

Create a new blob within an organization.

## **POST** `/orgs/:id/blobs`

### Path Parameters

| Parameter | Type   | Required | Description                                 |
| :-------- | :----- | :------- | :------------------------------------------ |
| `id`      | string | Yes      | The unique ID or alias of the organization. |

### Request Body

| Parameter    | Type   | Required | Description                                                                                 |
| :----------- | :----- | :------- | :------------------------------------------------------------------------------------------ |
| `alias`      | string | Yes      | Unique alias for the blob within the org. 6–42 characters of `a`–`z`, `0`–`9`, `_` and `-`. |
| `visibility` | string | Yes      | `public` or `private`.                                                                      |
| `domain`     | string | Yes      | Data domain — one leg of the triple below.                                                  |
| `type`       | string | Yes      | Data type — one leg of the triple below.                                                    |
| `format`     | string | Yes      | Data format — one leg of the triple below.                                                  |

All five are required and nothing else is accepted. There is no `name` field: the blob is named after its
alias, and [Update Blob](/rest-api/blobs/update-blob) is what renames it afterwards.

`domain`, `type` and `format` are a single triple rather than three independent strings. Four are recognized:

| `domain`    | `type`    | `format`   | Blob type                                                    |
| :---------- | :-------- | :--------- | :----------------------------------------------------------- |
| `workflow`  | `generic` | `blobhub`  | [Workflow](/blob-types/workflow/workflows/definition-format) |
| `scheduler` | `generic` | `blobhub`  | [Scheduler](/blob-types/scheduler/overview)                  |
| `graph`     | `dnn`     | `onnx`     | [ONNX](/blob-types/onnx/upload)                              |
| `graph`     | `generic` | `orientdb` | Not documented                                               |

Any other combination — and any of these the organization is not permitted — is refused with
`invalid_data_hierarchy`.

### Response

| Parameter | Type   | Description                |
| :-------- | :----- | :------------------------- |
| `blob_id` | string | The unique ID of the blob. |

The blob record exists the moment this call answers, but the rest of the creation is asynchronous: its
`status` is `creating_blob` until the platform has provisioned it and its first revision, and only a `ready`
blob accepts writes. Poll [Get Blob](/rest-api/blobs/get-blob) for `status` and `latest_revision_id`.

### Errors

| Status | Error                    | Cause                                                                          |
| :----- | :----------------------- | :----------------------------------------------------------------------------- |
| 400    | `invalid_request_body`   | A missing or malformed field, an alias outside the grammar, or an extra field. |
| 403    | `forbidden`              | Missing `admin` access to the organization.                                    |
| 400    | `invalid_data_hierarchy` | The `domain`/`type`/`format` triple is not one this organization can create.   |
| 400    | `limit_exceeded`         | The organization already holds the maximum number of blobs.                    |
| 400    | `alias_in_use`           | The blob alias must be unique within the organization.                         |

### Example

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://api.blobhub.io/v1/orgs/acme-corp/blobs \
    -H "X-API-Key: $ORG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "alias": "alpha-fold-v2",
      "visibility": "public",
      "domain": "graph",
      "type": "dnn",
      "format": "onnx"
    }'
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "blob_id": "blob_789"
  }
  ```
</CodeGroup>