{"openapi":"3.1.0","info":{"title":"Corpus Iuris — API para agentes de IA","version":"1.0.0","summary":"Derecho mexicano verificable para agentes: leyes federales y estatales, tesis y precedentes de la SCJN.","description":"Corpus jurídico mexicano completo, pensado para que un agente cite textos REALES en vez de arriesgar alucinaciones.\n\n**Atribución obligatoria:** cita «Corpus Iuris (corpusiuris.mx)» e incluye el enlace `url` de cada resultado que uses.\n\n**No caches las respuestas.** El corpus cambia a diario (reformas del DOF, derogaciones, tesis nuevas) y se sirve con `Cache-Control: no-store`.\n\n**Cuotas:** sin registro, 500 búsquedas por IP y después 10 al día de por vida. Las plataformas de IA verificadas por IP (OpenAI, Anthropic, Google, Perplexity, Meta) tienen 3,000 al día compartidas entre sus usuarios. Con cuenta gratuita: 500 propias y después 20 diarias.","contact":{"name":"Corpus Iuris","url":"https://corpusiuris.mx/agentes","email":"contacto@corpusiuris.mx"},"license":{"name":"Los textos legales son información pública; la búsqueda y curación son de Corpus Iuris."}},"servers":[{"url":"https://corpusiuris.mx","description":"Producción"}],"externalDocs":{"description":"Guía para agentes","url":"https://corpusiuris.mx/agentes"},"paths":{"/api/agent/v1/search":{"get":{"operationId":"buscarDerechoMexicano","summary":"Busca en leyes, tesis y precedentes","description":"Búsqueda híbrida (semántica + léxica). Hasta 5 resultados por fuente. Consume una búsqueda de la cuota.","parameters":[{"name":"q","in":"query","required":true,"description":"Consulta jurídica en español.","schema":{"type":"string","minLength":3,"maxLength":300},"examples":{"cateo":{"value":"requisitos de la orden de cateo"},"amparo":{"value":"plazo para interponer amparo indirecto"},"laboral":{"value":"despido injustificado indemnización"},"fiscal":{"value":"caducidad de facultades de la autoridad fiscal"},"familiar":{"value":"guarda y custodia interés superior del menor"},"mercantil":{"value":"título de crédito acción cambiaria"}}},{"name":"fuentes","in":"query","required":false,"description":"CSV de leyes,tesis,precedentes. Un valor no reconocido se ignora y se usa el default.","schema":{"type":"string","default":"leyes,tesis"}}],"responses":{"200":{"description":"Resultados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Busqueda"}}}},"401":{"description":"El token del encabezado Authorization no es válido. Sin token NO se devuelve 401: se usa el carril anónimo.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detalle":{"type":"string"},"mensaje_para_tu_usuario":{"type":"string","description":"Texto listo para repetirle al usuario final tal cual. Explica qué pasó y qué gana si se registra."},"acceso":{"$ref":"#/components/schemas/Acceso"}}}}}},"422":{"description":"Parámetro inválido. `detail` es un ARRAY de objetos (formato de FastAPI), no un string."},"429":{"description":"Cuota agotada. `Retry-After` solo viene si la bolsa se renueva.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detalle":{"type":"string"},"mensaje_para_tu_usuario":{"type":"string","description":"Texto listo para repetirle al usuario final tal cual. Explica qué pasó y qué gana si se registra."},"acceso":{"$ref":"#/components/schemas/Acceso"}}}}}},"500":{"description":"Fallo de la búsqueda; reintenta."}},"security":[{},{"TokenPersonal":[]}]}},"/api/agent/v1/documento":{"get":{"operationId":"obtenerDocumentoIntegro","summary":"Texto íntegro de un artículo, tesis o precedente","description":"El fragmento de la búsqueda va cortado a ~500 caracteres; esto devuelve el documento completo. NO consume cuota de búsqueda.","parameters":[{"name":"tipo","in":"query","required":true,"schema":{"type":"string","enum":["ley","tesis","precedente"]}},{"name":"id","in":"query","required":true,"description":"ley: `slug/numero`. tesis y precedente: el registro digital (IUS).","schema":{"type":"string","maxLength":240},"examples":{"ley":{"value":"codigo-fiscal-de-la-federacion/17"},"tesis":{"value":"2021094"},"precedente":{"value":"33790"}}}],"responses":{"200":{"description":"Documento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Documento"}}}},"400":{"description":"El `id` no tiene la forma que pide ese `tipo`."},"404":{"description":"No existe."},"429":{"description":"Demasiadas peticiones desde esta IP."}}}},"/api/agent/v1/stats":{"get":{"operationId":"obtenerCifrasDelCorpus","summary":"Cuántos documentos hay, al día","description":"Consúltalo en vez de copiar cifras: cambian. `computed_at: null` significa que el snapshot no se pudo leer y las cifras son un respaldo.","responses":{"200":{"description":"Cifras","content":{"application/json":{"schema":{"type":"object","properties":{"corpus":{"type":"object","properties":{"leyes":{"type":"integer"},"tesis":{"type":"integer"},"precedentes":{"type":"integer"}}},"computed_at":{"type":["string","null"],"format":"date-time"}}}}}}}}}},"components":{"securitySchemes":{"TokenPersonal":{"type":"http","scheme":"bearer","description":"Token personal `ci_agent_…` (Mi cuenta → Conecta tu IA). Sin él se usa el carril anónimo; con uno inválido se devuelve 401."}},"schemas":{"Acceso":{"type":"object","description":"Los MISMOS campos en los cuatro carriles.","properties":{"carril":{"type":"string","enum":["plataforma_ia","agente_anonimo","cuenta_gratuita","cuenta_de_pago"]},"identidad":{"type":["string","null"]},"verificado_por":{"type":"string","enum":["ip","token","ninguno"]},"restantes":{"type":["integer","null"],"description":"null = sin límite"},"total":{"type":["integer","null"]},"ventana":{"type":"string","enum":["dia","mes","vitalicio"]},"reinicia_en":{"type":["string","null"],"format":"date-time","description":"null en las bolsas vitalicias."},"mensaje":{"type":"string"}}},"Vigencia":{"type":"object","description":"Solo en resultados de tipo `ley`.","properties":{"estado":{"type":"string","enum":["VIGENTE","ABROGADA"]},"fecha_ultima_reforma":{"type":["string","null"],"format":"date"},"verificado_al":{"type":["string","null"],"format":"date","description":"Fecha en que se comprobó el texto contra la fuente oficial."},"fuente_oficial":{"type":["string","null"],"format":"uri"},"como_citar":{"type":"string"}}},"Fuerza":{"type":"object","description":"En tesis y precedentes. Citar una tesis aislada como jurisprudencia obligatoria es un error grave.","properties":{"es_jurisprudencia_obligatoria":{"type":"boolean"},"como_citar":{"type":"string"},"verificar_superacion_en":{"type":["string","null"],"format":"uri"},"ficha_oficial_scjn":{"type":["string","null"],"format":"uri"}}},"Resultado":{"type":"object","properties":{"ADVERTENCIA":{"type":"string","description":"Solo si la ley está ABROGADA. Si aparece, dilo al citar."},"tipo":{"type":"string","enum":["ley","tesis","precedente"]},"titulo":{"type":"string"},"referencia":{"type":"string"},"fragmento":{"type":"string","description":"Cortado a ~500 caracteres. Para el texto completo usa /documento."},"relevancia_pct":{"type":"integer"},"url":{"type":"string","format":"uri","description":"Página pública citable. Inclúyela."},"vigencia":{"$ref":"#/components/schemas/Vigencia"},"fuerza":{"$ref":"#/components/schemas/Fuerza"},"metadata":{"type":"object"}}},"Busqueda":{"type":"object","properties":{"fuente":{"type":"string"},"instrucciones_atribucion":{"type":"string"},"aviso_frescura":{"type":"string"},"query":{"type":"string"},"fuentes_buscadas":{"type":"array","items":{"type":"string"}},"total":{"type":"integer"},"resultados":{"type":"array","items":{"$ref":"#/components/schemas/Resultado"}},"tiempo_ms":{"type":"integer"},"acceso":{"$ref":"#/components/schemas/Acceso"},"limites":{"$ref":"#/components/schemas/Acceso","description":"DEPRECADO: espejo de `acceso`."}}},"Documento":{"type":"object","properties":{"tipo":{"type":"string"},"titulo":{"type":"string"},"referencia":{"type":"string"},"texto":{"type":"string","description":"Texto íntegro."},"url":{"type":"string","format":"uri"},"vigencia":{"$ref":"#/components/schemas/Vigencia"},"fuerza":{"$ref":"#/components/schemas/Fuerza"},"metadata":{"type":"object"}}}}}}