# Assets

## Create an asset upload

`client.Assets.New(ctx, body) (*AssetNewResponse, error)`

**post** `/assets`

Creates an asset from an allowlisted source URL or reserves a signed upload URL. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

### Parameters

- `body AssetNewParams`

  - `Source param.Field[string]`

    Asset source URL or signed-url upload mode

  - `WorkspaceID param.Field[string]`

    Workspace identifier

  - `ContentType param.Field[string]`

    Asset content type

  - `FileName param.Field[string]`

    Asset file name

  - `Folder param.Field[string]`

    Destination folder

### Returns

- `type AssetNewResponse struct{…}`

  - `AssetID string`

    Asset identifier

  - `Status AssetNewResponseStatus`

    - `const AssetNewResponseStatusPendingUpload AssetNewResponseStatus = "pending_upload"`

    - `const AssetNewResponseStatusReady AssetNewResponseStatus = "ready"`

    - `const AssetNewResponseStatusFailed AssetNewResponseStatus = "failed"`

  - `UploadedVia AssetNewResponseUploadedVia`

    Asset source

    - `const AssetNewResponseUploadedViaURL AssetNewResponseUploadedVia = "url"`

    - `const AssetNewResponseUploadedViaSignedURL AssetNewResponseUploadedVia = "signed_url"`

  - `URL string`

    Asset URL

  - `Visibility Workspace`

    - `const WorkspaceWorkspace Workspace = "workspace"`

  - `WorkspaceID string`

    Workspace identifier

  - `ExpiresAt Time`

    Expiration time for the upload URL

  - `Upload AssetNewResponseUpload`

    - `ContentType MultipartFormData`

      - `const MultipartFormDataMultipartFormData MultipartFormData = "multipart/form-data"`

    - `FileField File`

      - `const FileFile File = "file"`

    - `FormFields map[string, string]`

      Upload form fields

    - `Method Post`

      - `const PostPost Post = "POST"`

    - `URL string`

      Upload URL

  - `UploadURL string`

    Upload URL (serialized)

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/florafauna-ai/flora-go"
  "github.com/florafauna-ai/flora-go/option"
)

func main() {
  client := flora.NewClient(
    option.WithAPIKey("My API Key"),
  )
  asset, err := client.Assets.New(context.TODO(), flora.AssetNewParams{
    Source: "signed-url",
    WorkspaceID: "ws_abc123",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", asset.AssetID)
}
```

#### Response

```json
{
  "asset_id": "asset_abc123",
  "status": "pending_upload",
  "uploaded_via": "url",
  "url": "https://example.com",
  "visibility": "workspace",
  "workspace_id": "ws_abc123",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "upload": {
    "content_type": "multipart/form-data",
    "file_field": "file",
    "form_fields": {
      "foo": "string"
    },
    "method": "POST",
    "url": "https://example.com"
  },
  "upload_url": "https://upload.imagekit.io/api/v1/files/upload"
}
```

## Complete a signed asset upload

`client.Assets.Complete(ctx, assetID) (*AssetCompleteResponse, error)`

**post** `/assets/{assetId}/complete`

Marks a signed asset upload as complete after the file has been uploaded. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

### Parameters

- `assetID string`

  Asset identifier

### Returns

- `type AssetCompleteResponse struct{…}`

  - `AssetID string`

    Asset identifier

  - `Status AssetCompleteResponseStatus`

    - `const AssetCompleteResponseStatusPendingUpload AssetCompleteResponseStatus = "pending_upload"`

    - `const AssetCompleteResponseStatusReady AssetCompleteResponseStatus = "ready"`

    - `const AssetCompleteResponseStatusFailed AssetCompleteResponseStatus = "failed"`

  - `URL string`

    Asset URL

  - `Visibility Workspace`

    - `const WorkspaceWorkspace Workspace = "workspace"`

  - `WorkspaceID string`

    Workspace identifier

  - `ExpiresAt Time`

    Expiration time for the upload URL

  - `FailureMessage string`

    Failure message when the asset is in failed status

  - `Upload AssetCompleteResponseUpload`

    - `ContentType MultipartFormData`

      - `const MultipartFormDataMultipartFormData MultipartFormData = "multipart/form-data"`

    - `FileField File`

      - `const FileFile File = "file"`

    - `FormFields map[string, string]`

      Upload form fields

    - `Method Post`

      - `const PostPost Post = "POST"`

    - `URL string`

      Upload URL

  - `UploadURL string`

    Upload URL (serialized)

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/florafauna-ai/flora-go"
  "github.com/florafauna-ai/flora-go/option"
)

func main() {
  client := flora.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.Assets.Complete(context.TODO(), "asset_abc123")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.AssetID)
}
```

#### Response

```json
{
  "asset_id": "asset_abc123",
  "status": "pending_upload",
  "url": "https://example.com",
  "visibility": "workspace",
  "workspace_id": "ws_abc123",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "failure_message": "failure_message",
  "upload": {
    "content_type": "multipart/form-data",
    "file_field": "file",
    "form_fields": {
      "foo": "string"
    },
    "method": "POST",
    "url": "https://example.com"
  },
  "upload_url": "https://upload.imagekit.io/api/v1/files/upload"
}
```

## Retry a signed asset upload

`client.Assets.Retry(ctx, assetID) (*AssetRetryResponse, error)`

**post** `/assets/{assetId}/retry`

Creates a fresh signed upload reservation for a failed or expired asset upload. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

### Parameters

- `assetID string`

  Asset identifier

### Returns

- `type AssetRetryResponse struct{…}`

  - `AssetID string`

    Asset identifier

  - `Status AssetRetryResponseStatus`

    - `const AssetRetryResponseStatusPendingUpload AssetRetryResponseStatus = "pending_upload"`

    - `const AssetRetryResponseStatusReady AssetRetryResponseStatus = "ready"`

    - `const AssetRetryResponseStatusFailed AssetRetryResponseStatus = "failed"`

  - `URL string`

    Asset URL

  - `Visibility Workspace`

    - `const WorkspaceWorkspace Workspace = "workspace"`

  - `WorkspaceID string`

    Workspace identifier

  - `ExpiresAt Time`

    Expiration time for the upload URL

  - `FailureMessage string`

    Failure message when the asset is in failed status

  - `Upload AssetRetryResponseUpload`

    - `ContentType MultipartFormData`

      - `const MultipartFormDataMultipartFormData MultipartFormData = "multipart/form-data"`

    - `FileField File`

      - `const FileFile File = "file"`

    - `FormFields map[string, string]`

      Upload form fields

    - `Method Post`

      - `const PostPost Post = "POST"`

    - `URL string`

      Upload URL

  - `UploadURL string`

    Upload URL (serialized)

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/florafauna-ai/flora-go"
  "github.com/florafauna-ai/flora-go/option"
)

func main() {
  client := flora.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.Assets.Retry(context.TODO(), "asset_abc123")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.AssetID)
}
```

#### Response

```json
{
  "asset_id": "asset_abc123",
  "status": "pending_upload",
  "url": "https://example.com",
  "visibility": "workspace",
  "workspace_id": "ws_abc123",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "failure_message": "failure_message",
  "upload": {
    "content_type": "multipart/form-data",
    "file_field": "file",
    "form_fields": {
      "foo": "string"
    },
    "method": "POST",
    "url": "https://example.com"
  },
  "upload_url": "https://upload.imagekit.io/api/v1/files/upload"
}
```

## List assets

`client.Assets.List(ctx, query) (*AssetsCursorPage[AssetListResponse], error)`

**get** `/assets`

Returns assets visible to the authenticated public API key. Filter by workspace, project canvas, search query, cursor, and limit without exposing raw file bytes or internal graph data.

### Parameters

- `query AssetListParams`

  - `Cursor param.Field[string]`

    Opaque cursor for fetching the next page

  - `Limit param.Field[int64]`

    Maximum number of results to return

  - `ProjectID param.Field[string]`

    Project identifier

  - `Query param.Field[string]`

    Search query

  - `WorkspaceID param.Field[string]`

    Workspace identifier

### Returns

- `type AssetListResponse struct{…}`

  - `AssetID string`

    Asset identifier

  - `ContentType string`

    Asset content type

  - `CreatedAt int64`

  - `Description string`

    Asset description

  - `Height int64`

  - `Name string`

    Asset name

  - `SizeBytes int64`

  - `Status AssetListResponseStatus`

    - `const AssetListResponseStatusPendingUpload AssetListResponseStatus = "pending_upload"`

    - `const AssetListResponseStatusReady AssetListResponseStatus = "ready"`

    - `const AssetListResponseStatusFailed AssetListResponseStatus = "failed"`

  - `UploadContentType string`

    Content type provided at upload time

  - `UploadedVia string`

    Asset source

  - `URL string`

    Asset URL

  - `Width int64`

  - `WorkspaceID string`

    Workspace identifier

  - `NodeID string`

    Associated node identifier

  - `ProjectID string`

    Project identifier

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/florafauna-ai/flora-go"
  "github.com/florafauna-ai/flora-go/option"
)

func main() {
  client := flora.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Assets.List(context.TODO(), flora.AssetListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### Response

```json
{
  "assets": [
    {
      "asset_id": "asset_abc123",
      "content_type": "content_type",
      "created_at": 0,
      "description": "description",
      "height": 0,
      "name": "name",
      "size_bytes": 0,
      "status": "pending_upload",
      "upload_content_type": "upload_content_type",
      "uploaded_via": "uploaded_via",
      "url": "https://example.com",
      "width": 0,
      "workspace_id": "ws_abc123",
      "node_id": "node_abc123",
      "project_id": "prj_abc123"
    }
  ],
  "meta": {
    "next_cursor": "eyJvZmZzZXQiOjIwfQ",
    "total_estimate": 0
  }
}
```

## Get an asset

`client.Assets.Get(ctx, assetID) (*AssetGetResponse, error)`

**get** `/assets/{assetId}`

Returns metadata for one asset when it is accessible to the authenticated public API key. Missing and inaccessible assets both return 404.

### Parameters

- `assetID string`

  Asset identifier

### Returns

- `type AssetGetResponse struct{…}`

  - `AssetID string`

    Asset identifier

  - `ContentType string`

    Asset content type

  - `CreatedAt Time`

    Asset creation time (ISO 8601 datetime)

  - `Description string`

    Asset description

  - `FailureMessage string`

    Failure message when the asset is in failed status

  - `Height int64`

  - `Name string`

    Asset name

  - `SizeBytes int64`

  - `Status AssetGetResponseStatus`

    - `const AssetGetResponseStatusPendingUpload AssetGetResponseStatus = "pending_upload"`

    - `const AssetGetResponseStatusReady AssetGetResponseStatus = "ready"`

    - `const AssetGetResponseStatusFailed AssetGetResponseStatus = "failed"`

  - `UploadContentType string`

    Content type provided at upload time

  - `UploadedVia string`

    Asset source

  - `URL string`

    Asset URL

  - `Width int64`

  - `WorkspaceID string`

    Workspace identifier

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/florafauna-ai/flora-go"
  "github.com/florafauna-ai/flora-go/option"
)

func main() {
  client := flora.NewClient(
    option.WithAPIKey("My API Key"),
  )
  asset, err := client.Assets.Get(context.TODO(), "asset_abc123")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", asset.AssetID)
}
```

#### Response

```json
{
  "asset_id": "asset_abc123",
  "content_type": "content_type",
  "created_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "failure_message": "failure_message",
  "height": 0,
  "name": "name",
  "size_bytes": 0,
  "status": "pending_upload",
  "upload_content_type": "upload_content_type",
  "uploaded_via": "uploaded_via",
  "url": "https://example.com",
  "width": 0,
  "workspace_id": "ws_abc123"
}
```