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

# Types

## Analytics Types

### `AnalyticsQuery`

```typescript theme={null}
type AnalyticsQuery = {
  gateway_domain: string;
  start_date: string;
  end_date: string;
  cid?: string;
  file_name?: string;
  user_agent?: string;
  country?: string;
  region?: string;
  referer?: string;
  limit?: number;
  sort_order?: "asc" | "desc";
};
```

### `TopAnalyticsQuery`

```typescript theme={null}
type TopAnalyticsQuery = AnalyticsQuery & {
  sort_by: "requests" | "bandwidth";
  attribute: "cid" | "country" | "region" | "user_agent" | "referer" | "file_name";
};
```

### `TopAnalyticsResponse`

```typescript theme={null}
type TopAnalyticsResponse = {
  data: TopAnalyticsItem[];
};
```

### `TopAnalyticsItem`

```typescript theme={null}
type TopAnalyticsItem = {
  value: string;
  requests: number;
  bandwidth: number;
};
```

### `TimeIntervalAnalyticsQuery`

```typescript theme={null}
type TimeIntervalAnalyticsQuery = AnalyticsQuery & {
  sort_by?: "requests" | "bandwidth";
  date_interval: "day" | "week";
};
```

### `TimePeriodItem`

```typescript theme={null}
type TimePeriodItem = {
  period_start_time: string;
  requests: number;
  bandwidth: number;
};
```

### `TimeIntervalAnalyticsResponse`

```typescript theme={null}
type TimeIntervalAnalyticsResponse = {
  total_requests: number;
  total_bandwidth: number;
  time_periods: TimePeriodItem[];
};
```

### `UserPinnedDataResponse`

```typescript theme={null}
type UserPinnedDataResponse = {
  pin_count: number;
  pin_size_total: number;
  pin_size_with_replications_total: number;
};
```

## Config Types

### `PinataConfig`

```typescript theme={null}
type PinataConfig = {
  pinataJwt?: string;
  pinataGateway?: string;
  pinataGatewayKey?: string;
  customHeaders?: Record<string, string>;
  endpointUrl?: string;
  uploadUrl?: string;
};
```

## File Types

### `FileObject`

```typescript theme={null}
type FileObject = {
  name: string;
  size: number;
  type: string;
  lastModified: number;
  arrayBuffer: () => Promise<ArrayBuffer>;
};
```

### `JsonBody`

```typescript theme={null}
type JsonBody = Record<string, unknown>;
```

### `PinataMetadata`

```typescript theme={null}
type PinataMetadata = {
  name?: string;
  keyvalues?: Record<string, string>;
};
```

### `UpdateFileOptions`

```typescript theme={null}
type UpdateFileOptions = {
  id: string;
  name?: string;
  keyvalues?: Record<string, string>;
};
```

### `DeleteResponse`

```typescript theme={null}
type DeleteResponse = {
  id: string;
  status: string;
};
```

### `FileListItem`

```typescript theme={null}
type FileListItem = {
  id: string;
  name: string | null;
  cid: "pending" | string;
  size: number;
  number_of_files: number;
  mime_type: string;
  keyvalues: Record<string, string>;
  group_id: string | null;
  created_at: string;
};
```

### `FileListResponse`

```typescript theme={null}
type FileListResponse = {
  files: FileListItem[];
  next_page_token: string;
};
```

### `FileListQuery`

```typescript theme={null}
type FileListQuery = {
  name?: string;
  group?: string;
  noGroup?: boolean;
  mimeType?: string;
  cid?: string;
  cidPending?: boolean;
  metadata?: Record<string, string>;
  order?: "ASC" | "DESC";
  limit?: number;
  pageToken?: string;
};
```

### `PinQueueQuery`

```typescript theme={null}
type PinQueueQuery = {
  sort?: "ASC" | "DSC";
  status?: "prechecking" | "retrieving" | "expired" | "backfilled" | "over_free_limit" | "over_max_size" | "invalid_object" | "bad_host_node";
  cid?: string;
  limit?: number;
  pageToken?: string;
};
```

### `PinQueueItem`

```typescript theme={null}
type PinQueueItem = {
  id: string;
  cid?: string;
  ipfs_pin_hash?: string;
  date_queued: string;
  name: string;
  status: string;
  keyvalues: any;
  host_nodes: string[];
  pin_policy: {
    regions: {
      id: string;
      desiredReplicationCount: number;
    }[];
    version: number;
  };
};
```

### `PinQueueResponse`

```typescript theme={null}
type PinQueueResponse = {
  rows: PinQueueItem[];
  next_page_token: string;
};
```

### `SwapCidOptions`

```typescript theme={null}
type SwapCidOptions = {
  cid: string;
  swapCid: string;
};
```

### `SwapHistoryOptions`

```typescript theme={null}
type SwapHistoryOptions = {
  cid: string;
  domain: string;
};
```

### `SwapCidResponse`

```typescript theme={null}
type SwapCidResponse = {
  mapped_cid: string;
  created_at: string;
};
```

### `VectorizeFileResponse`

```typescript theme={null}
type VectorizeFileResponse = {
  status: boolean;
};
```

### `VectorizeQuery`

```typescript theme={null}
type VectorizeQuery = {
  groupId: string;
  query: string;
  returnFile?: boolean;
};
```

### `VectorQueryMatch`

```typescript theme={null}
type VectorQueryMatch = {
  file_id: string;
  cid: string;
  score: number;
};
```

### `VectorizeQueryResponse`

```typescript theme={null}
type VectorizeQueryResponse = {
  count: number;
  matches: VectorQueryMatch[];
};
```

## Gateway Types

### `ContentType`

```typescript theme={null}
type ContentType =
  | "application/json"
  | "application/xml"
  | "text/plain"
  | "text/html"
  | "text/css"
  | "text/javascript"
  | "application/javascript"
  | "image/jpeg"
  | "image/png"
  | "image/gif"
  | "image/svg+xml"
  | "audio/mpeg"
  | "audio/ogg"
  | "video/mp4"
  | "application/pdf"
  | "application/octet-stream"
  | string
  | null;
```

### `GetCIDResponse`

```typescript theme={null}
type GetCIDResponse = {
  data?: JSON | string | Blob | null;
  contentType: ContentType;
};
```

### `OptimizeImageOptions`

```typescript theme={null}
type OptimizeImageOptions = {
  width?: number;
  height?: number;
  dpr?: number;
  fit?: "scaleDown" | "contain" | "cover" | "crop" | "pad";
  gravity?: "auto" | "side" | string;
  quality?: number;
  format?: "auto" | "webp";
  animation?: boolean;
  sharpen?: number;
  onError?: boolean;
  metadata?: "keep" | "copyright" | "none";
};
```

### `AccessLinkOptions`

```typescript theme={null}
type AccessLinkOptions = {
  cid: string;
  date?: number;
  expires: number;
  gateway?: string;
};
```

### `ContainsCIDResponse`

```typescript theme={null}
type ContainsCIDResponse = {
  containsCid: boolean;
  cid: string | null;
};
```

## Group Types

### `GroupOptions`

```typescript theme={null}
type GroupOptions = {
  name: string;
  isPublic?: boolean;
};
```

### `UpdateGroupOptions`

```typescript theme={null}
type UpdateGroupOptions = {
  groupId: string;
  name?: string;
  isPublic?: boolean;
};
```

### `GetGroupOptions`

```typescript theme={null}
type GetGroupOptions = {
  groupId: string;
};
```

### `GroupListResponse`

```typescript theme={null}
type GroupListResponse = {
  groups: GroupResponseItem[];
  next_page_token: string;
};
```

### `GroupResponseItem`

```typescript theme={null}
type GroupResponseItem = {
  id: string;
  is_public: boolean;
  name: string;
  createdAt: string;
};
```

### `GroupQueryOptions`

```typescript theme={null}
type GroupQueryOptions = {
  name?: string;
  limit?: number;
  pageToken?: string;
  isPublic?: boolean;
};
```

### `GroupCIDOptions`

```typescript theme={null}
type GroupCIDOptions = {
  groupId: string;
  files: string[];
};
```

### `UpdateGroupFilesResponse`

```typescript theme={null}
type UpdateGroupFilesResponse = {
  id: string;
  status: string;
};
```

## Key Types

### `KeyPermissions`

```typescript theme={null}
type KeyPermissions = {
  admin?: boolean;
  endpoints?: Endpoints;
  resources?: ResourcePermission[];
};
```

### `ResourcePermission`

```typescript theme={null}
type ResourcePermission =
  | "org:read"
  | "org:write"
  | "org:files:read"
  | "org:files:write"
  | "org:groups:read"
  | "org:groups:write"
  | "org:gateways:read"
  | "org:gateways:write"
  | "org:analytics:read"
  | "org:analytics:write";
```

### `Endpoints`

```typescript theme={null}
type Endpoints = {
  data?: DataEndponts;
  pinning?: PinningEndpoints;
};
```

### `DataEndponts`

```typescript theme={null}
type DataEndponts = {
  pinList?: boolean;
  userPinnedDataTotal?: boolean;
};
```

### `PinningEndpoints`

```typescript theme={null}
type PinningEndpoints = {
  hashMetadata?: boolean;
  hashPinPolicy?: boolean;
  pinByHash?: boolean;
  pinFileToIPFS?: boolean;
  pinJSONToIPFS?: boolean;
  pinJobs?: boolean;
  unpin?: boolean;
  userPinPolicy?: boolean;
};
```

### `KeyOptions`

```typescript theme={null}
type KeyOptions = {
  keyName: string;
  permissions: KeyPermissions;
  maxUses?: number;
};
```

### `KeyResponse`

```typescript theme={null}
type KeyResponse = {
  JWT: string;
  pinata_api_key: string;
  pinata_api_secret: string;
};
```

### `KeyListQuery`

```typescript theme={null}
type KeyListQuery = {
  revoked?: boolean;
  limitedUse?: boolean;
  exhausted?: boolean;
  name?: string;
  offset?: number;
};
```

### `KeyListItem`

```typescript theme={null}
type KeyListItem = {
  id: string;
  name: string;
  key: string;
  secret: string;
  max_uses: number;
  uses: number;
  user_id: string;
  scopes: KeyScopes;
  revoked: boolean;
  createdAt: string;
  updatedAt: string;
};
```

### `KeyScopes`

```typescript theme={null}
type KeyScopes = {
  endpoints: {
    pinning: {
      pinFileToIPFS: boolean;
      pinJSONToIPFS: boolean;
    };
  };
  admin: boolean;
};
```

### `KeyListResponse`

```typescript theme={null}
type KeyListResponse = {
  keys: KeyListItem[];
  count: number;
};
```

### `RevokeKeyResponse`

```typescript theme={null}
type RevokeKeyResponse = {
  key: string;
  status: string;
};
```

## Signature Types

### `SignatureOptions`

```typescript theme={null}
type SignatureOptions = {
  cid: string;
  signature: string;
  address: string;
};
```

### `SignatureResponse`

```typescript theme={null}
type SignatureResponse = {
  cid: string;
  signature: string;
};
```

## Upload Types

### `UploadResponse`

```typescript theme={null}
type UploadResponse = {
  id: string;
  name: string;
  cid: string;
  size: number;
  created_at: string;
  number_of_files: number;
  mime_type: string;
  group_id: string | null;
  keyvalues: {
    [key: string]: string;
  };
  vectorized: boolean;
  network: string;
};
```

### `UploadOptions`

```typescript theme={null}
type UploadOptions = {
  metadata?: PinataMetadata;
  keys?: string;
  groupId?: string;
  vectorize?: boolean;
  url?: string;
  peerAddresses?: string[];
};
```

### `SignedUploadUrlOptions`

```typescript theme={null}
type SignedUploadUrlOptions = {
  date?: number;
  expires: number;
  groupId?: string;
  name?: string;
  keyvalues?: Record<string, string>;
  vectorize?: boolean;
  maxFileSize?: number;
  mimeTypes?: string[];
};
```

### `UploadCIDOptions`

```typescript theme={null}
type UploadCIDOptions = {
  metadata?: PinataMetadata;
  peerAddresses?: string[];
  keys?: string;
  groupId?: string;
};
```

### `PinByCIDResponse`

```typescript theme={null}
type PinByCIDResponse = {
  id: string;
  cid: string;
  date_queued: string;
  name: string;
  status: string;
  keyvalues: Record<string, any> | null;
  host_nodes: string[] | null;
  group_id: string | null;
};
```