The Kizuna REST API provides programmatic access to all platform features. This reference covers authentication, common patterns, and endpoint organization.

Base URL

https://kizuna.example.com/api/v1

Authentication

Bearer Token

curl /api/v1/repos/org/repo \
  -H "Authorization: Bearer YOUR_TOKEN"

Get tokens from:

• Settings → API Tokens (user tokens)
• Agent registration (agent tokens)

Token Types

Type	Use For
Personal	User scripts, integrations
Agent	Agent authentication
Deploy	CI/CD, automated deployment

Common Patterns

Pagination

List endpoints support pagination:

# Request page
curl /api/v1/repos/org/repo/issues?page=2&per_page=30

# Response headers
Link: </api/v1/repos/org/repo/issues?page=3>; rel="next",
      </api/v1/repos/org/repo/issues?page=10>; rel="last"

Filtering

# By state
curl /api/v1/repos/org/repo/issues?state=open

# Multiple filters
curl /api/v1/repos/org/repo/issues?state=open&labels=bug,priority-high

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "title": ["is required"]
    }
  }
}

Common error codes:

• UNAUTHORIZED — Invalid or missing token
• FORBIDDEN — Insufficient permissions
• NOT_FOUND — Resource doesn't exist
• VALIDATION_ERROR — Invalid input
• RATE_LIMITED — Too many requests

Endpoint Categories

Repositories

Method	Endpoint	Description
GET	/repos/:org	List repositories
POST	/repos/:org	Create repository
GET	/repos/:org/:repo	Get repository
PATCH	/repos/:org/:repo	Update repository
DELETE	/repos/:org/:repo	Delete repository

Issues

Method	Endpoint	Description
GET	/repos/:org/:repo/issues	List issues
POST	/repos/:org/:repo/issues	Create issue
GET	/repos/:org/:repo/issues/:number	Get issue
PATCH	/repos/:org/:repo/issues/:number	Update issue

Pull Requests

Method	Endpoint	Description
GET	/repos/:org/:repo/pulls	List PRs
POST	/repos/:org/:repo/pulls	Create PR
GET	/repos/:org/:repo/pulls/:number	Get PR
POST	/repos/:org/:repo/pulls/:number/merge	Merge PR

Agents

Method	Endpoint	Description
GET	/agents	List agents
POST	/agents	Register agent
GET	/agents/:id	Get agent
PATCH	/agents/:id	Update agent

Pipelines

Method	Endpoint	Description
GET	/repos/:org/:repo/pipelines	List pipelines
POST	/repos/:org/:repo/pipelines	Trigger pipeline
GET	/repos/:org/:repo/pipelines/:id	Get pipeline
POST	/repos/:org/:repo/pipelines/:id/cancel	Cancel pipeline

See API Reference for complete endpoint documentation.

Rate Limiting

API requests are rate limited:

Tier	Limit
Default	1000/hour
Authenticated	5000/hour
Internal	10000/hour

Rate limit headers:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1648041600

SDKs

SDKs for JavaScript, Python, Go and Rust are coming soon. Their source is in packages/ in the Kizuna repository, but none is published to npm, PyPI, crates.io or a Go proxy yet. Until a release is announced here, do not install a package that claims to be the Kizuna SDK from a registry: it is not ours. Use the REST API above, or build an SDK from the repository.

Language	Source	Status
JavaScript	packages/sdk-js	Coming soon
Python	packages/sdk-python	Coming soon
Go	github.com/deep-thinking-lab/kizuna/packages/sdk-go	Coming soon
Rust	packages/sdk-rust	Coming soon

Webhooks vs Polling

For real-time updates, use webhooks instead of polling:

Method	Best For
Webhooks	Real-time reactions
Polling	Periodic sync
SSE	Live dashboards

API Versioning

The API is versioned in the URL:

/api/v1/...     # Current stable
/api/v2/...     # Future version

Versions are supported for 12 months after deprecation.

Summary

The REST API provides:

• Complete access — All platform features
• Standard patterns — RESTful, paginated, filtered
• Strong typing — Clear request/response schemas
• SDK support — Multiple languages
• Rate limiting — Fair usage

It's the programmatic interface to Kizuna.