---
title: "Subscribe to a global source"
method: POST
path: "/sources/subscribe"
tags: ["Sources"]
---

# Subscribe to a global source

`POST /sources/subscribe`

Subscribe to an existing globally indexed public source. Creates a local reference for instant access without re-indexing.

## Request body

- GlobalSourceSubscribeRequest — Request model for subscribing to a global source
  - `url` string, required — URL of the source (GitHub repo, docs URL, arXiv URL/ID, or HuggingFace dataset URL)
  - `source_type` 'repository' | 'documentation' | 'research_paper' | 'huggingface_dataset', nullable — Source type. Auto-detected from URL if not provided.
  - `ref` string, nullable — Git ref for repositories (branch, tag, or commit SHA)

## Response `200`

Successful Response

- GlobalSourceSubscribeResponse — Response model for global source subscription
  - `action` string, required — Action taken: instant_access | wait_for_indexing | not_indexed | use_private | indexing_started
  - `message` string, required — Human-readable description of the action
  - `global_source_id` string, nullable — Canonical ID of the global source
  - `namespace` string, nullable — TurboPuffer namespace for the source
  - `status` string, nullable — Current status of the global source
  - `local_reference_id` string, nullable — ID of the created local reference (project/data_source)
  - `display_name` string, nullable — Display name of the source

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/trynia/apis/nia-ai-api.md) · [All operations](https://skmtc.net/trynia/apis/nia-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trynia/nia-ai-api/versions/d216ffc3efb6/schema)