Gerenciar repositórios

O mka1-repos é o serviço de repositórios da plataforma para pesos de modelo e datasets. Cada repositório é um repositório git comum com Git LFS, pertencente a exatamente uma organização e identificado pelo par <org>/<name> — por exemplo acme/qwen2.5-0.5b-support. Esse identificador é o ponto central. Você envia artefatos ao repositório a partir da sua máquina via git, e as cargas de trabalho do Compute resolvem o mesmo <org>/<name> através do endpoint de artefatos compatível com Hugging Face da plataforma para treinar com eles ou servi-los — veja Usar repositórios com o Compute. Este guia cobre a API de gerenciamento: criar repositórios, listá-los e consultá-los, renomeá-los e excluí-los.

Antes de começar

Você precisa de:

Requisito	Observações
Chave de API	Envie-a como `Authorization: Bearer <mka1-api-key>` em toda requisição.
Papel de proprietário ou administrador da organização	Todos os endpoints de repositório são restritos a proprietários e administradores da organização. Não há permissões por repositório; o acesso é decidido apenas pelo seu papel na organização.

Os repositórios sempre pertencem à organização de quem faz a chamada. Você nunca escolhe o org na criação — ele é derivado da sua chave de API — e não é possível acessar repositórios de outra organização de forma alguma.

Criar um repositório

Escolha um nome e, opcionalmente, uma descrição. O nome deve começar com uma letra ou dígito e ter no máximo 100 caracteres entre letras, dígitos, pontos, sublinhados e hífens (^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$).

import { SDK } from '@meetkai/mka1';

const sdk = new SDK({
  bearerAuth: 'Bearer <mka1-api-key>',
});

const repo = await sdk.repos.create({
  createRepoRequest: {
    name: 'qwen2.5-0.5b-support',
    description: 'Fine-tuned weights for the acme assistant.',
  },
});
console.log(repo.org, repo.name, repo.id);

curl https://apigw.mka1.com/api/v1/repos \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "name": "qwen2.5-0.5b-support",
    "description": "Fine-tuned weights for the acme assistant."
  }'

A resposta é 201 com o repositório:

{
  "id": "rqz4h6k2m5n7p9r3t5v7w9x2",
  "org": "acme",
  "name": "qwen2.5-0.5b-support",
  "description": "Fine-tuned weights for the acme assistant.",
  "created_at": "2026-07-30T09:15:00Z"
}

id é um identificador opaco e estável — a chave canônica que sobrevive a renomeações. org e name são os rótulos visíveis ao usuário que formam a referência do repositório e suas URLs. A criação provisiona o repositório git subjacente como parte da requisição. Se esse provisionamento falhar, a criação retorna 502 provision_failed e nada é mantido, então é seguro tentar novamente. O corpo da requisição rejeita campos desconhecidos, e um nome que já está em uso na sua organização retorna 409.

A referência do repositório e a URL git

Dois valores identificam um repositório em todo o restante da plataforma:

Valor	Formato	Usado para
Referência do repositório	`<org>/<name>`, por exemplo `acme/qwen2.5-0.5b-support`	Resolução compatível com Hugging Face dentro de cargas de trabalho do Compute e em ferramentas como ms-swift e vLLM.
URL git	`https://git.mka1.com/<org>/<name>.git`	`git clone`, `git push` e transferências Git LFS a partir das suas próprias máquinas.

O host git autentica com HTTP basic auth: qualquer nome de usuário é aceito (o slug da sua organização é a convenção), e a senha é uma chave de API MKA1. Esses dois valores são o que você entrega a uma carga de trabalho do Compute como variáveis de ambiente — o passo a passo está em Usar repositórios com o Compute.

Listar repositórios

Retorna todos os repositórios da sua organização.

const { repos } = await sdk.repos.list({});
for (const repo of repos) {
  console.log(`${repo.org}/${repo.name}`, repo.description);
}

curl https://apigw.mka1.com/api/v1/repos \
  --header 'Authorization: Bearer <mka1-api-key>'

{
  "repos": [
    {
      "id": "rqz4h6k2m5n7p9r3t5v7w9x2",
      "org": "acme",
      "name": "qwen2.5-0.5b-support",
      "description": "Fine-tuned weights for the acme assistant.",
      "created_at": "2026-07-30T09:15:00Z"
    },
    {
      "id": "rb8s2d4f6h8j1l3n5q7s9v2x",
      "org": "acme",
      "name": "support-conversations",
      "description": "Curated support transcripts for fine-tuning.",
      "created_at": "2026-07-28T16:40:00Z"
    }
  ]
}

Recuperar um repositório

Consulte um único repositório pela sua referência.

const repo = await sdk.repos.get({
  org: 'acme',
  name: 'qwen2.5-0.5b-support',
});
console.log(repo.description);

curl https://apigw.mka1.com/api/v1/repos/acme/qwen2.5-0.5b-support \
  --header 'Authorization: Bearer <mka1-api-key>'

Um repositório que não existe na sua organização retorna 404 — incluindo qualquer repositório que pertença a outra organização.

Renomear ou atualizar um repositório

As atualizações afetam apenas rótulos: você pode alterar name e description, e um campo omitido permanece inalterado.

const repo = await sdk.repos.update({
  org: 'acme',
  name: 'qwen2.5-0.5b-support',
  patchRepoRequest: {
    name: 'qwen2.5-0.5b-support-v2',
  },
});
console.log(repo.name);

curl https://apigw.mka1.com/api/v1/repos/acme/qwen2.5-0.5b-support \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{"name": "qwen2.5-0.5b-support-v2"}'

O id do repositório é estável, então uma renomeação é uma atualização de metadados — o histórico git e os artefatos armazenados ficam intactos. Renomear para um nome que já existe na sua organização retorna 409.

Uma renomeação altera a referência do repositório e a URL git.O antigo <org>/<name> deixa de resolver imediatamente. Atualize todo remote git, todo valor de ambiente REPO/REPO_URL em corpos de criação do Compute e todo script de treinamento ou de inferência que referenciava o nome antigo.

Excluir um repositório

await sdk.repos.delete({
  org: 'acme',
  name: 'qwen2.5-0.5b-support',
});

curl https://apigw.mka1.com/api/v1/repos/acme/qwen2.5-0.5b-support \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

A resposta é 204, sem corpo. O registro do repositório é removido imediatamente — essa exclusão é autoritativa — enquanto o desmonte do armazenamento git subjacente é uma limpeza em regime de melhor esforço. Uma exclusão repetida da mesma referência retorna 404.

Excluir um repositório remove o repositório, seu histórico git e todos os artefatos armazenados. Isso não pode ser desfeito — não há exclusão reversível nem janela de recuperação.

Erros

Os endpoints de repositório retornam um envelope uniforme com um código estável legível por máquina e o ID de correlação da requisição:

{
  "error": "not_found",
  "correlation_id": "c0a8f3d2-4b6e-4f1a-9c7d-2e5b8a1f6d3c"
}

Status	Código	Significado
`400`	`invalid_name`, `invalid_body`	Um nome que viola o padrão, ou um corpo malformado ou campo desconhecido (os corpos rejeitam propriedades desconhecidas).
`401`	`unauthorized`	Identidade com escopo de organização ausente ou incompleta na requisição.
`403`	`forbidden`	Quem chama não é proprietário nem administrador da organização.
`404`	`not_found`	O repositório não existe na sua organização — um repositório de outra organização é reportado como `404`, nunca `403`, para que a existência nunca vaze.
`409`	`name_taken`	O nome já está em uso na sua organização (criação ou renomeação).
`500`	`internal`	Um erro inesperado no servidor.
`502`	`provision_failed`	O repositório git subjacente não pôde ser criado; o repositório não foi mantido, então repita a criação.
`503`	`org_unresolved`	O gateway não conseguiu resolver sua organização; tente novamente e contate o suporte se persistir.

Referência da API

Para o esquema completo de requisição e resposta, abra os grupos de Repositórios na Referência de API.

Veja também

Usar repositórios com o Compute - envie pesos e datasets, depois treine ou sirva a partir deles.
Executar um job de ajuste fino - publique pesos mesclados em um repositório a partir de um job de treinamento.
Implantar um servidor de modelos - sirva pesos diretamente de um repositório com vLLM.

Primeiros passos

Respostas

Recursos

Compute

CLI

Receitas

Benchmarks

Infraestrutura

Gerenciar repositórios

Antes de começar

Criar um repositório

A referência do repositório e a URL git

Listar repositórios

Recuperar um repositório

Renomear ou atualizar um repositório

Excluir um repositório

Erros

Referência da API

Veja também

​Antes de começar

​Criar um repositório

​A referência do repositório e a URL git

​Listar repositórios

​Recuperar um repositório

​Renomear ou atualizar um repositório

​Excluir um repositório

​Erros

​Referência da API

​Veja também

Antes de começar

Criar um repositório

A referência do repositório e a URL git

Listar repositórios

Recuperar um repositório

Renomear ou atualizar um repositório

Excluir um repositório

Erros

Referência da API

Veja também