{"schema_version":"mia-geo.agent-api.v1","provider":"mia-geo","base_url":"https://mia-geo-sit.ambr.io","publication_path":"/agent-contract/v1.json","generated_from":{"kind":"fastapi_openapi_allowlist","openapi_version":"3.1.0","api_version":"0.2.0"},"contract_status":"stable","consumer_allowlist_required":false,"product_to_product_surfaces":[{"path_prefix":"/api/","credential":"account_bound_mia_service_key","required_headers":["Authorization","MIA-Account-Id"],"optional_audit_headers":["MIA-Initiated-By-User-Id"],"initiator_authority":"audit_only","human_owned_routes_allowed":true,"excluded_operations":["browser_identity","administrator_management"]}],"billing":{"customer_unit":"MIA Points"},"measurement_lifecycle":{"current_active_states":["admitting","queued","running","cancel_pending"],"current_terminal_states":["done","partial","failed","cancelled"],"status_reads_are_authoritative":true,"future_standardization_issue":9},"compatibility_policy":{"additive_changes":"allowed_within_v1","breaking_changes":"require_v2","deprecation_notice_days":90,"v1_support_window":"until_v2_notice_plus_90_days"},"operations":[{"operation_id":"geo.models.list","method":"GET","path":"/api/models","resource_scope":"model_catalog.read","parent_resource":null,"authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"model_catalog.read","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"models_models_get","parameters":[],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}},{"operation_id":"geo.projects.list","method":"GET","path":"/api/projects","resource_scope":"owned_project.list","parent_resource":"account_context","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_project.list","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"list_projects_projects_get","parameters":[{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"}}],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}},{"operation_id":"geo.projects.create","method":"POST","path":"/api/projects","resource_scope":"owned_project.create","parent_resource":"account_context","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_project.create","effect_class":"reversible_write","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"conflict_on_duplicate","idempotency_key":"project_name"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"},{"category":"conflict","http_status":409,"retryable":false,"recovery":"select_the_existing_project_or_change_the_name"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"create_project_projects_post","parameters":[],"request_body":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":true}},{"operation_id":"geo.brands.list","method":"GET","path":"/api/brands","resource_scope":"owned_brand.list","parent_resource":"account_context","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_brand.list","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"list_brands_brands_get","parameters":[{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"}},{"name":"project_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Project Id"}}],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}},{"operation_id":"geo.brands.create","method":"POST","path":"/api/brands","resource_scope":"owned_brand.create","parent_resource":"account_context","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_brand.create","effect_class":"reversible_write","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"conflict_on_duplicate","idempotency_key":"unsupported"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"},{"category":"conflict","http_status":409,"retryable":false,"recovery":"select_the_existing_brand_or_change_the_name"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"create_brand_brands_post","parameters":[],"request_body":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":true}},{"operation_id":"geo.brand_keywords.list","method":"GET","path":"/api/brands/{brand_id}/keywords","resource_scope":"owned_brand.read","parent_resource":"brand_id","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_brand.read","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"list_keywords_brands__brand_id__keywords_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"integer","title":"Brand Id"}}],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}},{"operation_id":"geo.brand_keywords.create","method":"POST","path":"/api/brands/{brand_id}/keywords","resource_scope":"owned_brand.measurement_scope","parent_resource":"brand_id","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_brand.measurement_scope","effect_class":"reversible_write","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"idempotent_reconcile","idempotency_key":"brand_topic_market_language"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"add_keyword_brands__brand_id__keywords_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"integer","title":"Brand Id"}}],"request_body":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":true}},{"operation_id":"geo.keyword.get","method":"GET","path":"/api/keywords/{keyword_id}","resource_scope":"owned_keyword.read","parent_resource":"keyword_id","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_keyword.read","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"get_keyword_keywords__keyword_id__get","parameters":[{"name":"keyword_id","in":"path","required":true,"schema":{"type":"integer","title":"Keyword Id"}}],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}},{"operation_id":"geo.keyword_insight.get","method":"GET","path":"/api/keywords/{keyword_id}/insight","resource_scope":"owned_keyword.read","parent_resource":"keyword_id","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_keyword.read","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"},{"category":"conflict","http_status":409,"retryable":false,"recovery":"select_a_monitoring_profile"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"insight_keywords__keyword_id__insight_get","parameters":[{"name":"keyword_id","in":"path","required":true,"schema":{"type":"integer","title":"Keyword Id"}},{"name":"monitoring_profile_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Monitoring Profile Id"}}],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}},{"operation_id":"geo.run.estimate","method":"POST","path":"/api/estimate","resource_scope":"owned_keyword.measure","parent_resource":"keyword_id","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_keyword.measure","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"signed_precondition","schema_negotiation":{"header":"X-MIA-GEO-Estimate-Schema","default":"mia-geo.run-estimate.v1","supported":["mia-geo.run-estimate.v1","mia-geo.run-estimate.v3"]},"idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"},{"category":"contract_version","http_status":406,"retryable":false,"recovery":"request_a_supported_estimate_schema"},{"category":"billing","http_status":503,"retryable":true,"recovery":"retry_when_mia_points_pricing_is_available"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"estimate_cost_estimate_post","parameters":[{"name":"X-MIA-GEO-Estimate-Schema","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Mia-Geo-Estimate-Schema"}}],"request_body":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateReq"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":true}},{"operation_id":"geo.run.start","method":"POST","path":"/api/keywords/{keyword_id}/runs","resource_scope":"owned_keyword.measure","parent_resource":"keyword_id","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_keyword.measure","effect_class":"paid","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"signed_estimate_precondition","required_fields":["estimate_token","expected_points"],"schema_negotiation":{"header":"X-MIA-GEO-Estimate-Schema","default":"mia-geo.run-estimate.v1","supported":["mia-geo.run-estimate.v1","mia-geo.run-estimate.v3"]},"idempotency_key":"unsupported_pending_mia_geo_issue_9"},"lifecycle":"asynchronous_run","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"},{"category":"contract_version","http_status":406,"retryable":false,"recovery":"request_a_supported_estimate_schema"},{"category":"billing","http_status":402,"retryable":false,"recovery":"add_mia_points"},{"category":"conflict","http_status":409,"retryable":false,"recovery":"request_and_confirm_a_fresh_estimate"},{"category":"retryable_outage","http_status":503,"retryable":true,"recovery":"check_authoritative_run_status_before_retrying"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"trigger_run_keywords__keyword_id__runs_post","parameters":[{"name":"keyword_id","in":"path","required":true,"schema":{"type":"integer","title":"Keyword Id"}},{"name":"X-MIA-GEO-Estimate-Schema","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Mia-Geo-Estimate-Schema"}}],"request_body":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":true}},{"operation_id":"geo.runs.list","method":"GET","path":"/api/runs","resource_scope":"owned_run.list","parent_resource":"account_context","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_run.list","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"list_runs_runs_get","parameters":[{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"}},{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Brand Id"}},{"name":"keyword_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Id"}},{"name":"task_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Task Id"}},{"name":"monitoring_profile_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Monitoring Profile Id"}},{"name":"before_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Before Id"}},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"title":"Limit"}},{"name":"include_internal","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Internal"}}],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}},{"operation_id":"geo.run.get","method":"GET","path":"/api/runs/{run_id}","resource_scope":"owned_run.read","parent_resource":"run_id","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_run.read","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"synchronous","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"get_run_runs__run_id__get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","title":"Run Id"}},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"}}],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}},{"operation_id":"geo.run.status","method":"GET","path":"/api/runs/{run_id}/status","resource_scope":"owned_run.read","parent_resource":"run_id","authentication":{"accepted_credentials":["oidc_session","account_bound_mia_pat","account_bound_mia_service_key"],"api_automation_credential":"account_bound_mia_pat","platform_key_requires_headers":["Authorization","MIA-Account-Id"],"account_context":"required","product_account_model":"immutable_platform_account_with_geo_project_data_scope","authorization_source":"mia_platform_terminal_context_and_mia_geo_resource_ownership"},"minimum_role":"authenticated_principal","capability":"owned_run.read","effect_class":"read","delegated_policy_eligible":true,"agent_policy_eligible":true,"concurrency":{"mode":"safe_read","idempotency_key":"not_applicable"},"lifecycle":"authoritative_status_read","errors":[{"category":"authentication","http_status":401,"retryable":false,"recovery":"authenticate_with_a_supported_terminal_identity"},{"category":"permission","http_status":403,"retryable":false,"recovery":"use_an_identity_that_owns_the_resource"},{"category":"validation","http_status":422,"retryable":false,"recovery":"correct_the_request"},{"category":"internal","http_status":500,"retryable":true,"recovery":"retry_with_backoff_then_contact_support"}],"introduced_in":"mia-geo.agent-api.v1","deprecated":false,"wire":{"openapi_operation_id":"run_status_runs__run_id__status_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","title":"Run Id"}}],"request_body":null,"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"success_response_schema_status":"untyped_openapi_pending_issue_8","rejects_unknown_request_fields":false}}],"components":{"schemas":{"BrandIn":{"properties":{"name":{"type":"string","maxLength":200,"title":"Name"},"aliases":{"items":{"type":"string","maxLength":200},"type":"array","maxItems":20,"title":"Aliases"},"landing_url":{"type":"string","maxLength":500,"title":"Landing Url","default":""},"region":{"type":"string","maxLength":50,"title":"Region","default":"中国大陆"},"language":{"type":"string","maxLength":50,"title":"Language","default":"简体中文"},"industry":{"type":"string","maxLength":200,"title":"Industry","default":""},"primary_platform":{"type":"string","maxLength":40,"title":"Primary Platform","default":"DeepSeek"},"site_mode":{"type":"string","enum":["website","materials","hybrid"],"title":"Site Mode","default":"website"},"project_id":{"type":"integer","minimum":1.0,"title":"Project Id"},"keywords":{"items":{"$ref":"#/components/schemas/KeywordIn"},"type":"array","maxItems":50,"title":"Keywords"}},"additionalProperties":false,"type":"object","required":["name","project_id"],"title":"BrandIn"},"EntityAliasesIn":{"properties":{"name":{"type":"string","maxLength":200,"title":"Name"},"aliases":{"items":{"type":"string","maxLength":200},"type":"array","maxItems":20,"title":"Aliases"},"existence_status":{"type":"string","enum":["confirmed","pending_confirmation"],"title":"Existence Status","default":"pending_confirmation"},"confirmation_source":{"anyOf":[{"type":"string","enum":["manual","user_confirmation"]},{"type":"null"}],"title":"Confirmation Source"}},"additionalProperties":false,"type":"object","required":["name"],"title":"EntityAliasesIn","description":"规范实体名 + 同一实体的明确名称变体；业务线/子品牌不是别名。"},"EstimateReq":{"properties":{"keyword_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Keyword Id"},"models":{"items":{"type":"string"},"type":"array","title":"Models"},"total_questions":{"type":"integer","minimum":0.0,"title":"Total Questions","default":0},"samples":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Samples","default":1},"cycle":{"type":"string","enum":["once","hourly","daily","weekly","monthly"],"title":"Cycle","default":"once"},"week_days":{"items":{"type":"integer"},"type":"array","maxItems":7,"title":"Week Days"},"month_days":{"items":{"type":"integer"},"type":"array","maxItems":31,"title":"Month Days"},"runs_per_round":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Runs Per Round","default":1},"run_type":{"type":"string","enum":["baseline","post","scheduled","manual"],"title":"Run Type","default":"baseline"},"web_search":{"type":"boolean","title":"Web Search","default":true},"measurement_mode":{"type":"string","enum":["market_context","controlled_benchmark","native_observation"],"title":"Measurement Mode","default":"controlled_benchmark"},"monitoring_profile_id":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Monitoring Profile Id"}},"additionalProperties":false,"type":"object","title":"EstimateReq"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeywordIn":{"properties":{"expected_keyword_id":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Expected Keyword Id","description":"Omit to allow merge. A positive ID freezes an existing Topic. Explicit null requires a new Topic and distinct supplied questions; an existing Topic is rejected under the brand lock."},"text":{"type":"string","maxLength":200,"title":"Text"},"market":{"type":"string","maxLength":16,"minLength":2,"title":"Market","default":"CN"},"language":{"anyOf":[{"type":"string","maxLength":16,"minLength":2},{"type":"null"}],"title":"Language"},"target_markets":{"items":{"type":"string"},"type":"array","maxItems":1,"title":"Target Markets"},"competitors":{"items":{"anyOf":[{"type":"string","maxLength":200},{"$ref":"#/components/schemas/EntityAliasesIn"}]},"type":"array","maxItems":50,"title":"Competitors","description":"Applied for a new Topic or question_selection_mode=replace. Ignored for an existing Topic in merge mode; inspect competitor_selection in the receipt."},"longtails":{"items":{"$ref":"#/components/schemas/LongtailIn"},"type":"array","maxItems":200,"title":"Longtails"},"question_selection_mode":{"type":"string","enum":["merge","replace"],"title":"Question Selection Mode","description":"merge appends questions and preserves existing competitors. replace atomically applies the complete reviewed longtails AND competitors sets; omitted entries are removed from the active selection. Read the existing Topic first and preserve every intended question and competitor when recovering configuration.","default":"merge"}},"additionalProperties":false,"type":"object","required":["text"],"title":"KeywordIn"},"LongtailIn":{"properties":{"text":{"type":"string","maxLength":400,"title":"Text"},"source":{"type":"string","maxLength":20,"title":"Source","default":"manual"},"intent":{"anyOf":[{"type":"string","enum":["recommendation","comparison","discovery","scenario","purchase_decision"],"description":"Use a canonical intent. Legacy aliases are normalized for compatibility."},{"type":"null"}],"title":"Intent"},"cluster":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Cluster"},"measurement_scope":{"type":"string","enum":["benchmark","brand_probe","quickwin"],"title":"Measurement Scope","default":"benchmark"},"demand_signal":{"additionalProperties":true,"type":"object","title":"Demand Signal"}},"additionalProperties":false,"type":"object","required":["text"],"title":"LongtailIn"},"ProjectIn":{"properties":{"name":{"type":"string","maxLength":200,"title":"Name"},"description":{"type":"string","maxLength":500,"title":"Description","default":""}},"additionalProperties":false,"type":"object","required":["name"],"title":"ProjectIn","description":"新建项目/工作区（单账号内对品牌分组）。"},"RetryingRunScopeInput":{"properties":{"request_id":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Request Id"},"version":{"type":"string","const":"mia-geo-run-scope/v2","title":"Version"},"questions":{"items":{"$ref":"#/components/schemas/RunQuestionInput"},"type":"array","maxItems":100,"minItems":1,"title":"Questions"},"lanes":{"items":{"type":"string","enum":["target_market","global_supplemental"]},"type":"array","maxItems":2,"minItems":1,"title":"Lanes"},"measurement_mode":{"type":"string","enum":["controlled_benchmark","native_observation"],"title":"Measurement Mode","default":"controlled_benchmark"},"samples":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Samples","default":1},"request_policy":{"type":"string","enum":["market_context","verbatim_question"],"title":"Request Policy"},"attempts_per_slot":{"type":"integer","const":1,"title":"Attempts Per Slot","default":1},"max_model_attempts":{"type":"integer","maximum":2000.0,"minimum":1.0,"title":"Max Model Attempts"},"research_objective":{"type":"string","maxLength":1200,"minLength":1,"title":"Research Objective"},"audience":{"type":"string","maxLength":500,"minLength":1,"title":"Audience"},"retrieval":{"$ref":"#/components/schemas/RunRetrievalInput"}},"additionalProperties":false,"type":"object","required":["version","questions","lanes","request_policy","max_model_attempts","research_objective","audience","retrieval"],"title":"RetryingRunScopeInput","description":"Opt-in v2. V1 serialization remains the exact already-admitted contract."},"RunIn":{"properties":{"run_scope":{"anyOf":[{"$ref":"#/components/schemas/RunScopeInput"},{"$ref":"#/components/schemas/RetryingRunScopeInput"},{"type":"null"}],"title":"Run Scope"},"models":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Models"},"type":{"type":"string","enum":["baseline","post","scheduled","manual"],"title":"Type","default":"baseline"},"web_search":{"type":"boolean","title":"Web Search","default":true},"measurement_mode":{"type":"string","enum":["market_context","controlled_benchmark","native_observation"],"title":"Measurement Mode","default":"controlled_benchmark"},"monitoring_profile_id":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Monitoring Profile Id"},"expected_points":{"anyOf":[{"type":"integer","maximum":1000000000000.0,"minimum":0.0},{"type":"null"}],"title":"Expected Points"},"estimate_token":{"anyOf":[{"type":"string","minLength":32},{"type":"null"}],"title":"Estimate Token"}},"additionalProperties":false,"type":"object","title":"RunIn"},"RunQuestionInput":{"properties":{"longtail_id":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Longtail Id"},"text":{"anyOf":[{"type":"string","maxLength":400,"minLength":1},{"type":"null"}],"title":"Text"},"source":{"type":"string","enum":["user_supplied","geo_generated","agent_drafted","existing_question"],"title":"Source"},"intent":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Intent"},"cluster":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Cluster"}},"additionalProperties":false,"type":"object","required":["source"],"title":"RunQuestionInput"},"RunRetrievalInput":{"properties":{"strategy":{"type":"string","const":"same_query","title":"Strategy","default":"same_query"},"max_attempts_per_question_lane":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Max Attempts Per Question Lane"}},"additionalProperties":false,"type":"object","required":["max_attempts_per_question_lane"],"title":"RunRetrievalInput","description":"Shared search budget; distinct from the model's one-attempt slot budget."},"RunScopeInput":{"properties":{"request_id":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Request Id"},"version":{"type":"string","const":"mia-geo-run-scope/v1","title":"Version","default":"mia-geo-run-scope/v1"},"questions":{"items":{"$ref":"#/components/schemas/RunQuestionInput"},"type":"array","maxItems":100,"minItems":1,"title":"Questions"},"lanes":{"items":{"type":"string","enum":["target_market","global_supplemental"]},"type":"array","maxItems":2,"minItems":1,"title":"Lanes"},"measurement_mode":{"type":"string","enum":["controlled_benchmark","native_observation"],"title":"Measurement Mode","default":"controlled_benchmark"},"samples":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Samples","default":1},"request_policy":{"type":"string","enum":["market_context","verbatim_question"],"title":"Request Policy"},"attempts_per_slot":{"type":"integer","const":1,"title":"Attempts Per Slot","default":1},"max_model_attempts":{"type":"integer","maximum":2000.0,"minimum":1.0,"title":"Max Model Attempts"},"research_objective":{"type":"string","maxLength":1200,"minLength":1,"title":"Research Objective"},"audience":{"type":"string","maxLength":500,"minLength":1,"title":"Audience"}},"additionalProperties":false,"type":"object","required":["questions","lanes","request_policy","max_model_attempts","research_objective","audience"],"title":"RunScopeInput"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"contract_hash":"559aca7c1b277639b6159b2445178f22d9a91b1e481b0a83210aba567fe36523"}