The Upload Source from GitHub endpoint lets you ingest content directly from a GitHub repository into your GraphorLM project.

Endpoint Overview

Authentication

This endpoint requires authentication using an API token. Include your API token as a Bearer token in the Authorization header.
Learn how to create and manage API tokens in the API Tokens guide.

Request Format

Headers

HeaderValueRequired
AuthorizationBearer YOUR_API_TOKEN✅ Yes
Content-Typeapplication/json✅ Yes

Request Body

Send a JSON body with the following field:
FieldTypeDescriptionRequired
urlstringThe GitHub repository URL to ingest (e.g., https://github.com/org/repo)✅ Yes

Repository Requirements

Response Format

Success Response (200 OK)

{
  "status": "Processing",
  "message": "Source processed successfully",
  "file_name": "https://github.com/org/repo",
  "file_size": 0,
  "file_type": "",
  "file_source": "github",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_name": "My Project",
  "partition_method": "basic"
}

Response Fields

FieldTypeDescription
statusstringProcessing status (New, Processing, Completed, Failed, etc.)
messagestringHuman-readable status message
file_namestringThe repository URL
file_sizeintegerSize in bytes (0 for initial GitHub record)
file_typestringDetected file type (when applicable)
file_sourcestringSource type (github)
project_idstringUUID of the project
project_namestringName of the project
partition_methodstringDocument processing method used

Code Examples

JavaScript/Node.js

import fetch from 'node-fetch';

const uploadGithubSource = async (apiToken, repoUrl) => {
  const response = await fetch('https://sources.graphorlm.com/upload-github-source', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url: repoUrl })
  });

  if (!response.ok) {
    throw new Error(`GitHub upload failed: ${response.status} ${response.statusText}`);
  }

  const result = await response.json();
  console.log('GitHub upload accepted:', result);
  return result;
};

// Usage
uploadGithubSource('grlm_your_api_token_here', 'https://github.com/org/repo');

Python

import requests

def upload_github_source(api_token, repo_url):
    endpoint = "https://sources.graphorlm.com/upload-github-source"
    headers = {"Authorization": f"Bearer {api_token}", "Content-Type": "application/json"}
    payload = {"url": repo_url}

    response = requests.post(endpoint, headers=headers, json=payload, timeout=300)
    response.raise_for_status()
    return response.json()

# Usage
result = upload_github_source("grlm_your_api_token_here", "https://github.com/org/repo")
print("GitHub upload accepted:", result["file_name"])  # echoes the repo URL

cURL

curl -X POST https://sources.graphorlm.com/upload-github-source \
  -H "Authorization: Bearer grlm_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/org/repo"}'

Error Responses

Common Error Codes

Status CodeError TypeDescription
400Bad RequestInvalid or missing URL, malformed JSON
401UnauthorizedInvalid or missing API token
403ForbiddenAccess denied to the specified project
404Not FoundProject or source not found
500Internal Server ErrorError during repository processing

Error Response Format

{
  "detail": "Invalid input: URL is required"
}

Error Examples

Document Processing

After a successful request, GraphorLM begins processing the GitHub source in the background.

Processing Stages

  1. Request Accepted - The request is validated and scheduled
  2. Repository Fetch - Repository content is retrieved
  3. Text Extraction - Content is extracted and normalized
  4. Structure Recognition - Document elements are identified and classified
  5. Ready for Use - Content is available for chunking and retrieval
You can reprocess sources using the Process Source endpoint after ingestion.

Best Practices

  • Provide valid repository URLs: Use the canonical HTTPS GitHub URL
  • Public repositories only: Private repositories are not supported
  • Retry logic: Implement retries for transient network issues

Next Steps