Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bitrecs.ai/llms.txt

Use this file to discover all available pages before exploring further.

The /submit endpoint accepts a finalized miner artifact, verifies it against the Bittensor chain commitment, runs a cosine similarity check against existing agents, and stores it in the evaluation queue. Unlike /check, this endpoint writes to the database and is the authoritative submission path. Miners must commit their Gist hash on-chain before calling this endpoint, and the request must include transport-layer authentication headers in addition to the submission signature.
Submitting is permanent. Once an artifact is accepted, the hotkey and Gist ID are locked for the current evaluation cycle. Use the POST /check endpoint to validate your artifact before committing to the chain.

​
Request

POST https://v2.api.bitrecs.ai/submit

​
Required headers

​
X-Signature
string
required
Transport-layer Ed25519 signature. Signs a canonical string composed of the submission body, X-Nonce, X-T-Nonce, and X-Timestamp.
​
X-Timestamp
string
required
Unix timestamp (seconds) of the request. The server rejects timestamps that are too old or too far in the future.
​
X-Nonce
string
required
Random nonce string included in the transport signature payload to prevent replay attacks.
​
X-T-Nonce
string
required
Secondary transport nonce. Both nonces are incorporated when computing and verifying X-Signature.

​
Body

​
created_at
string
required
ISO 8601 timestamp that must match the Gist’s created_at field exactly.
​
github_account
string
required
GitHub username that owns the Gist.
​
gist_id
string
required
GitHub Gist ID containing the YAML artifact.
​
hotkey
string
required
Miner’s Bittensor SS58 hotkey. Must be registered on the subnet and match miner_hotkey inside the artifact YAML.
​
signature
string
required
Ed25519 signature of the submission payload, proving the request originated from the stated hotkey.

​
Response (201)

​
artifact_id
string
required
UUID assigned to the newly stored artifact.
​
request_id
string
required
Unique hex request identifier for tracing and support purposes.
​
message
string
required
Human-readable confirmation, e.g. "Artifact submitted successfully".
​
similarity_check
string
required
Whether cosine similarity checking was active — "enabled" or "disabled".
​
similar_results
array
List of existing agents whose cosine distance from this submission fell below the similarity threshold. Each entry has an agent_id (string) and a distance (float). An empty array means no similar agents were found.

​
Error responses

StatusMeaning
400Bad request — invalid input, signature mismatch, timestamp expired, failed chain commitment, or artifact validation error.
402Payment required — payment check failed or insufficient funds.
409Conflict — this upload request was already processed (duplicate detection).
429Too many requests — rate limit exceeded.
500Internal server error — unexpected server-side failure. The request_id in the response can be used for support.
503Service unavailable — submissions are disabled or insufficient validators are connected.

​
Example

curl --request POST \
  --url https://v2.api.bitrecs.ai/submit \
  --header 'Content-Type: application/json' \
  --header 'X-Signature: 0xdeadbeef...' \
  --header 'X-Timestamp: 1727784000' \
  --header 'X-Nonce: a1b2c3d4e5f6' \
  --header 'X-T-Nonce: z9y8x7w6v5u4' \
  --data '{
    "created_at": "2025-10-01T12:00:00+00:00",
    "github_account": "my-github-user",
    "gist_id": "abc123def456abc123def456abc12345",
    "hotkey": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
    "signature": "0x1a2b3c..."
  }'
Success response (201) 
{
  "artifact_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "request_id": "d8e8fca2dc0f896fd7cb4cb0031ba249",
  "message": "Artifact submitted successfully",
  "similarity_check": "enabled",
  "similar_results": []
}
Error response (400) — timestamp expired 
{
  "detail": "Invalid or expired timestamp"
}
Error response (503) — system disabled 
{
  "detail": "Submissions are currently disabled. Please try again later."
}