{"openapi":"3.1.0","info":{"title":"Hire an Agent experiment","version":"0.1.0","description":"Rule-based directory of specialist agents plus the two specialists' plain JSON endpoints. A2A endpoints wrap the same contracts in an A2A message with one data part."},"servers":[{"url":"https://hireanagent.dev"}],"paths":{"/api/discover":{"post":{"summary":"Find matching, reachable specialist agents","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"v1"},"request_id":{"type":"string","minLength":1},"trace_id":{"type":"string","minLength":1},"task_summary":{"type":"string","minLength":1,"maxLength":2000},"required_skills":{"minItems":1,"type":"array","items":{"type":"string","enum":["link_audit","source_support","discover_agents"]}},"input_media_type":{"default":"application/json","type":"string"},"output_media_type":{"default":"application/json","type":"string"},"language":{"default":"de","type":"string"}},"required":["schema_version","request_id","trace_id","task_summary","required_skills","input_media_type","output_media_type","language"],"additionalProperties":false}}}},"responses":{"200":{"description":"matched, no_match or temporarily_unavailable","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"v1"},"request_id":{"type":"string"},"status":{"type":"string","enum":["matched","no_match","temporarily_unavailable"]},"candidates":{"type":"array","items":{"type":"object","properties":{"agent_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"skill_ids":{"type":"array","items":{"type":"string"}},"card_url":{"type":"string","format":"uri"},"endpoint_url":{"type":"string","format":"uri"},"contract_url":{"type":"string","format":"uri"},"agent_version":{"type":"string"},"match_reasons":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"availability":{"type":"string","enum":["reachable","unreachable","unknown"]},"health_checked_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["agent_id","name","description","skill_ids","card_url","endpoint_url","contract_url","agent_version","match_reasons","limitations","availability","health_checked_at"],"additionalProperties":false}},"reason":{"type":"string"},"sort_rule":{"type":"string"}},"required":["schema_version","request_id","status","candidates","sort_rule"],"additionalProperties":false}}}}}}},"/api/agents/{id}":{"get":{"summary":"One registered agent with its last reachability check","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"agent record","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"provider_name":{"type":"string"},"card_url":{"type":"string","format":"uri"},"endpoint_url":{"type":"string","format":"uri"},"protocol_version":{"type":"string"},"agent_version":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"input_media_types":{"type":"array","items":{"type":"string"}},"output_media_types":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"contract_url":{"type":"string","format":"uri"},"enabled":{"type":"boolean"},"health_status":{"type":"string","enum":["reachable","unreachable","unknown"]},"health_checked_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"health_error":{"type":["string","null"]}},"required":["id","name","description","provider_name","card_url","endpoint_url","protocol_version","agent_version","skills","limitations","input_media_types","output_media_types","languages","contract_url","enabled","health_status","health_checked_at","health_error"],"additionalProperties":false}}}},"404":{"description":"unknown id"}}}},"/api/health":{"get":{"summary":"Operational state of the directory","responses":{"200":{"description":"ok"}}}}},"x-specialists":{"link_audit":{"base_url":"https://links.hireanagent.dev","run":"https://links.hireanagent.dev/api/run","request":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"v1"},"request_id":{"type":"string","minLength":1},"trace_id":{"type":"string","minLength":1},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"expected_final_url":{"type":"string","format":"uri"},"expected_anchor":{"type":"string"}},"required":["item_id","url"],"additionalProperties":false}}},"required":["schema_version","request_id","trace_id","items"],"additionalProperties":false},"result":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"v1"},"request_id":{"type":"string"},"trace_id":{"type":"string"},"agent_id":{"type":"string"},"agent_version":{"type":"string"},"status":{"type":"string","enum":["completed","partial","failed"]},"findings":{"type":"array","items":{"type":"object","properties":{"finding_id":{"type":"string"},"item_id":{"type":"string"},"verdict":{"type":"string","enum":["ok","broken","redirect_problem","target_mismatch","unverifiable"]},"requested_url":{"type":"string"},"final_url":{"type":["string","null"]},"final_status":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"redirect_chain":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"location":{"type":["string","null"]}},"required":["url","status","location"],"additionalProperties":false}},"anchor_found":{"type":["boolean","null"]},"evidence":{"type":"string"},"checked_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["finding_id","item_id","verdict","requested_url","final_url","final_status","redirect_chain","anchor_found","evidence","checked_at"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}},"usage":{"type":"object","properties":{"input_tokens":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"output_tokens":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"cache_read_tokens":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"cache_write_tokens":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"web_requests":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"search_requests":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"model_calls":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"cost_usd":{"default":0,"type":"number","minimum":0}},"required":["input_tokens","output_tokens","cache_read_tokens","cache_write_tokens","web_requests","search_requests","model_calls","cost_usd"],"additionalProperties":false},"started_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"finished_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["schema_version","request_id","trace_id","agent_id","agent_version","status","findings","limitations","usage","started_at","finished_at"],"additionalProperties":false}},"source_support":{"base_url":"https://sources.hireanagent.dev","run":"https://sources.hireanagent.dev/api/run","request":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"v1"},"request_id":{"type":"string","minLength":1},"trace_id":{"type":"string","minLength":1},"claims":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"claim_id":{"type":"string","minLength":1},"claim":{"type":"string","minLength":1,"maxLength":1000},"source_urls":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","format":"uri"}},"as_of":{"type":"string"}},"required":["claim_id","claim","source_urls"],"additionalProperties":false}},"language":{"default":"de","type":"string"}},"required":["schema_version","request_id","trace_id","claims","language"],"additionalProperties":false},"result":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"v1"},"request_id":{"type":"string"},"trace_id":{"type":"string"},"agent_id":{"type":"string"},"agent_version":{"type":"string"},"status":{"type":"string","enum":["completed","partial","failed"]},"findings":{"type":"array","items":{"type":"object","properties":{"finding_id":{"type":"string"},"claim_id":{"type":"string"},"verdict":{"type":"string","enum":["supported","partially_supported","contradicted","not_supported","unverifiable"]},"source_url":{"type":["string","null"]},"quote":{"type":["string","null"]},"locator":{"type":["string","null"]},"rationale":{"type":"string"},"checked_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["finding_id","claim_id","verdict","source_url","quote","locator","rationale","checked_at"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}},"usage":{"type":"object","properties":{"input_tokens":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"output_tokens":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"cache_read_tokens":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"cache_write_tokens":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"web_requests":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"search_requests":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"model_calls":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"cost_usd":{"default":0,"type":"number","minimum":0}},"required":["input_tokens","output_tokens","cache_read_tokens","cache_write_tokens","web_requests","search_requests","model_calls","cost_usd"],"additionalProperties":false},"started_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"finished_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["schema_version","request_id","trace_id","agent_id","agent_version","status","findings","limitations","usage","started_at","finished_at"],"additionalProperties":false}}}}