---
title: "Import link study attachments"
method: POST
path: "/api/v1/research/study-attachments/import-link"
tags: ["research"]
---

# Import link study attachments

`POST /api/v1/research/study-attachments/import-link`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/research/study-attachments/import-link`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Attach a study file by its link instead of uploading it: Point11 checks the link is safe, fetches the file it points to, and admits it exactly as an upload (an image or a PDF up to 4 MiB, MP3 or WAV audio up to 4 MiB, a plain text, Markdown or CSV file up to 256 KB, or an MP4 or WebM video up to 100 MiB whose server states its size). The type is the one the link's server names, else the one the file's name names, and the bytes must prove it. A web page is refused: link the file itself. Returns the attachment, ready to reference from a study question; retrying with the same Idempotency-Key answers the same file without fetching the link again. When the link's safety check cannot run, it answers 503: try again. A video also returns its storyboard, which starts as preparing: read research_study_attachments_get_v2 until it is ready, refused or failed.

## Headers

- `Point11-Organization` string, uuid
- `Idempotency-Key` string, uuid, required

## Request body

- ResearchStudyAttachmentsImportLinkRequest
  - `url` string, required: The link to the file: an image, PDF, audio, text or video file.

## Response `200`

Success.

- ResearchStudyAttachmentsImportLinkResponse
  - `id` string, uuid, required
  - `filename` string, required
  - `mediaType` 'image/png' | 'image/jpeg' | 'image/webp' | 'application/pdf' | 'text/plain' | 'text/markdown' | 'text/csv' | 'video/mp4' | 'video/webm' | 'audio/mpeg' | 'audio/wav', required
  - `byteLength` integer, required
  - `status` 'pending' | 'ready', required: pending until research.study-attachments.complete-upload.v2 proves the upload.
  - `storyboard` ResearchStoryboard, nullable, required: A video's storyboard; null for every other file.
    - `status` 'preparing' | 'ready' | 'refused' | 'failed', required: preparing while the frames and transcript are made; ready once they exist; refused when the file cannot be used (see refusalCode); failed when preparation could not finish. Replace a refused or failed video by uploading it again.
    - `refusalCode` 'unsupported_container' | 'unsupported_video_codec' | 'unsupported_audio_codec' | 'no_video_stream' | 'too_long' | 'undecodable', nullable, required: Why a refused video cannot be used; null otherwise.
    - `durationMs` integer, nullable, required
    - `modelByteLength` integer, nullable, required: What a ready video counts toward a study's attachment bound: its frames and transcript, never the video file.
    - `frames` object[], required
      - `atMs` integer, required: When in the video this frame was taken.
      - `artifactId` string, uuid, required: Read the picture with research.study-attachments.download.v1.
      - `width` integer, required
      - `height` integer, required
    - `transcript` object, nullable, required: What was said, in timed segments; no segments for a silent video.
      - `language` string, nullable, required
      - `segments` object[], required
        - `startMs` integer, required
        - `endMs` integer, required
        - `text` string, required

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `402`: Billing refused the write: the code names the reason and `details.reason` carries it.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/5241805fe425?raw)