tendril/kb/02_systems/2025-11-11--gitea-api-reference--howto.md

title, date, captured_at, author, source, source_type, project, related_projects, topics, tags, type, status, phase_relevance, routing_hint, proposed_path, routing_confidence, related, summary, key_takeaways, action_candidates

title	date	captured_at	author	source	source_type	project	related_projects	topics	tags	type	status	phase_relevance	routing_hint	proposed_path	routing_confidence	related	summary	key_takeaways	action_candidates
Gitea API Reference	2025-11-11	2025-11-11	datawarrior	kind ref doc docs/GITEA/Gitea-API-Reference.md	personal_note	tendril	tendril	gitea api programming integration mcp	gitea api programming integration mcp rest-api	howto	active		Gitea API reference guide - infrastructure/tooling documentation	kb/02_systems/	0.95	docs/GITEA/Gitea-API-Reference.md src/mcp_server_gitea.rs	API differences and considerations when working with Gitea programmatically. Covers authentication, common endpoints, differences from GitHub API, and MCP server integration for Tendril.

Gitea API Reference

Overview

Gitea provides a REST API that is similar to GitHub's API but not identical. The API allows programmatic access to repositories, issues, pull requests, and more.

Base URL: https://your-gitea-instance.com/api/v1

For Tendril: https://git.parkingmeter.info/api/v1

Authentication

Personal Access Token

Creating a token:

1. Log in to Gitea
2. Go to Settings → Applications → Generate New Token
3. Set name and permissions
4. Copy token

Using token:

curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user

In code (Rust example):

let client = reqwest::Client::new();
let response = client
    .get("https://git.parkingmeter.info/api/v1/user")
    .header("Authorization", format!("token {}", token))
    .send()
    .await?;

Common Endpoints

User Information

Get authenticated user:

GET /api/v1/user

Get user by username:

GET /api/v1/users/{username}

Repositories

List repositories:

GET /api/v1/user/repos
GET /api/v1/users/{username}/repos
GET /api/v1/orgs/{org}/repos

Get repository:

GET /api/v1/repos/{owner}/{repo}

Create repository:

POST /api/v1/user/repos

Issues

List issues:

GET /api/v1/repos/{owner}/{repo}/issues

Get issue:

GET /api/v1/repos/{owner}/{repo}/issues/{index}

Create issue:

POST /api/v1/repos/{owner}/{repo}/issues

Pull Requests

List pull requests:

GET /api/v1/repos/{owner}/{repo}/pulls

Get pull request:

GET /api/v1/repos/{owner}/{repo}/pulls/{index}

Create pull request:

POST /api/v1/repos/{owner}/{repo}/pulls

Differences from GitHub API

1. Base URL

• GitHub: https://api.github.com
• Gitea: https://your-instance.com/api/v1

2. Issue/PR Numbers

• GitHub: Uses sequential numbers across repository
• Gitea: Uses index (similar, but may differ in some cases)

3. Some Endpoints

• Gitea may have different endpoints for some operations
• Check Gitea API documentation for specific endpoints
• Most common operations are similar

4. Webhooks

• Gitea webhooks are compatible with GitHub format
• Same payload structure
• Same event types (push, pull_request, etc.)

For LLMs: API Usage Guidelines

When Documenting API Usage

Reference Gitea API:

## API Integration

This project uses the **Gitea API** for programmatic access.

**Base URL**: `https://git.parkingmeter.info/api/v1`

**Authentication**: Personal Access Token

**Example**:
```bash
curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user/repos

### When Creating API Clients

**Use Gitea base URL**:
```rust
const GITEA_BASE_URL: &str = "https://git.parkingmeter.info/api/v1";

Use Gitea authentication:

let client = reqwest::Client::new();
let response = client
    .get(&format!("{}/user", GITEA_BASE_URL))
    .header("Authorization", format!("token {}", token))
    .send()
    .await?;

Common Use Cases

1. Listing Repositories

curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user/repos

2. Creating an Issue

curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New Issue","body":"Issue description"}' \
  https://git.parkingmeter.info/api/v1/repos/owner/repo/issues

3. Creating a Pull Request

curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"PR Title","head":"feature-branch","base":"main"}' \
  https://git.parkingmeter.info/api/v1/repos/owner/repo/pulls

MCP Server Integration

Tendril uses the Gitea MCP server for integration with Zed IDE. The MCP server provides:

• Repository management
• Issue management
• Pull request management
• File operations
• And more

Reference: See src/mcp_server_gitea.rs for implementation details.

References

• Gitea API Docs: https://docs.gitea.com/api/
• API Overview: https://docs.gitea.com/api/overview/
• Authentication: https://docs.gitea.com/api/authentication/

---

Original Location: docs/GITEA/Gitea-API-Reference.md
Last Updated: 2025-01-27
Related:

• src/mcp_server_gitea.rs - MCP server implementation
• docs/GITEA/Gitea-Basics.md