{"openapi":"3.1.0","info":{"title":"Pictor agent API","version":"1.0.0","description":"Buy Pictor credits and rent GPU instances. Paid operations use x402 through InFlow (1 credit = 1 USD)."},"servers":[{"url":"https://apiv2.pictor.network"}],"components":{"securitySchemes":{"aepApiKey":{"type":"apiKey","in":"header","name":"x-aep-api-key","description":"Credential issued by AEP Grant after enrolling at /.well-known/aep.","x-aep-authentication-method":"api-key"},"pictorApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Pictor API key created in the Pictor dashboard."}}},"paths":{"/api/agent/credits/balance":{"get":{"operationId":"getCreditBalance","summary":"Check the current Pictor credit balance before renting a GPU","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"responses":{"200":{"description":"Current Pictor credit balance and its raw on-chain value"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"503":{"description":"Credit balance is temporarily unavailable"}}}},"/api/agent/credits/purchase":{"post":{"operationId":"buyCredits","summary":"Buy credits (1 credit = 1 USD), paid with x402","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"credits","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":1000}}],"responses":{"200":{"description":"Paid; credits are sent after settlement"},"400":{"description":"Invalid credits"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"402":{"description":"x402 payment required. The `PAYMENT-REQUIRED` header lists the accepted payment options (InFlow); replay the request with `PAYMENT-SIGNATURE`."}}}},"/api/agent/credits/purchases/{purchaseId}":{"get":{"operationId":"getCreditPurchase","summary":"State of a credit purchase","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"purchaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Purchase state"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"404":{"description":"Not found"}}}},"/api/agent/instances/quotes":{"post":{"operationId":"quoteGpuInstance","summary":"Quote a personal Linux GPU instance (free, valid 5 minutes, single use)","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["duration","ssh_key_ids"],"properties":{"gpu_id":{"type":"integer","minimum":1},"gpu_count":{"type":"integer","minimum":1},"storage":{"type":"number","minimum":1,"description":"GB"},"selected_offer_id":{"type":"integer","minimum":1},"region":{"type":"string"},"duration":{"type":"integer","minimum":1,"maximum":720,"description":"hours"},"auto_renew":{"type":"boolean","default":false},"ssh_key_ids":{"type":"array","minItems":1,"items":{"type":"integer"}},"instance_name":{"type":"string","maxLength":100},"ports":{"type":"array","items":{"type":"integer","minimum":1,"maximum":65535}}}}}}},"responses":{"201":{"description":"Quote: quote_id, hourly_price, total_usd, expires_at, pay_url"},"400":{"description":"Invalid request or over the order limit"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"403":{"description":"SSH key not owned by the account"},"409":{"description":"No machine available"}}}},"/api/agent/instances":{"post":{"operationId":"payGpuInstanceQuote","summary":"Pay a quote with x402; the instance is created after settlement","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"quote_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paid; poll the order"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"402":{"description":"x402 payment required. The `PAYMENT-REQUIRED` header lists the accepted payment options (InFlow); replay the request with `PAYMENT-SIGNATURE`."},"404":{"description":"Unknown quote"},"409":{"description":"Quote already used"},"410":{"description":"Quote expired"}}}},"/api/agent/instances/rent":{"post":{"operationId":"rentGpuInstanceWithCredits","summary":"Rent a GPU instance using the existing Pictor credit balance","description":"Creates the instance through the normal Pictor rental flow and deducts its cost from Pictor credits. If the balance is insufficient, buy credits through buyCredits first.","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["duration","ssh_key_ids"],"properties":{"gpu_id":{"type":"integer","minimum":1},"gpu_count":{"type":"integer","minimum":1},"storage":{"type":"number","minimum":1,"description":"GB"},"selected_offer_id":{"type":"integer","minimum":1},"region":{"type":"string"},"duration":{"type":"integer","minimum":1,"maximum":720,"description":"hours"},"auto_renew":{"type":"boolean","default":false},"ssh_key_ids":{"type":"array","minItems":1,"items":{"type":"integer"}},"instance_name":{"type":"string","maxLength":100},"ports":{"type":"array","items":{"type":"integer","minimum":1,"maximum":65535}}}}}}},"responses":{"201":{"description":"Credits deducted and instance created"},"400":{"description":"Invalid request or insufficient Pictor credits"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"403":{"description":"SSH key not owned by the account"},"409":{"description":"No machine available"}}}},"/api/agent/instances/catalog/gpus":{"get":{"operationId":"listGpuTypes","summary":"List GPU types before choosing a rental configuration","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"min_vram","in":"query","required":false,"schema":{"type":"number","minimum":1}},{"name":"available","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"GPU types, specifications, hourly prices, and availability"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."}}}},"/api/agent/instances/catalog/availability":{"get":{"operationId":"checkGpuAvailability","summary":"Check availability after selecting a GPU type","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"gpu_id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"gpu_count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"region","in":"query","required":false,"schema":{"type":"string","default":"all"}}],"responses":{"200":{"description":"Availability for the selected GPU type and count"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"404":{"description":"GPU type not found"}}}},"/api/agent/instances/ssh-keys":{"get":{"operationId":"listSshKeys","summary":"List SSH keys before configuring a GPU instance","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"responses":{"200":{"description":"Personal SSH keys available for instance access"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."}}},"post":{"operationId":"createSshKey","summary":"Create an SSH key when the account does not have one yet","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","public_key"],"properties":{"name":{"type":"string"},"public_key":{"type":"string","description":"OpenSSH public key, never a private key"}}}}}},"responses":{"201":{"description":"SSH key created"},"400":{"description":"Invalid public key"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."}}}},"/api/agent/instances/orders/{orderId}":{"get":{"operationId":"getGpuInstanceOrder","summary":"State of a GPU instance order","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order state and lease id"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"404":{"description":"Not found"}}}},"/api/agent/instances/{leaseId}/start":{"post":{"operationId":"startGpuInstance","summary":"Start a stopped or paused GPU instance","description":"Starting an instance may resume credit consumption. Show the target instance and obtain user confirmation before calling.","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"leaseId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"x-user-confirmation-required":true,"responses":{"200":{"description":"Instance start requested"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"403":{"description":"Instance not owned by this account"},"404":{"description":"Instance not found"}}}},"/api/agent/instances/{leaseId}/stop":{"post":{"operationId":"stopGpuInstance","summary":"Stop a running or starting GPU instance","description":"Show the target instance and obtain user confirmation before calling.","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"leaseId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"x-user-confirmation-required":true,"responses":{"200":{"description":"Instance stop requested"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"403":{"description":"Instance not owned by this account"},"404":{"description":"Instance not found"}}}},"/api/agent/instances/{leaseId}":{"get":{"operationId":"getGpuInstance","summary":"One of your GPU instances (read-only)","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"leaseId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Instance details"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"404":{"description":"Not found"}}},"delete":{"operationId":"terminateGpuInstance","summary":"Permanently terminate a GPU instance","description":"Destructive and irreversible. Show the target instance and obtain explicit user confirmation immediately before calling.","security":[{"aepApiKey":[]},{"pictorApiKey":[]}],"parameters":[{"name":"leaseId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"x-user-confirmation-required":true,"x-destructive":true,"responses":{"200":{"description":"Instance permanently terminated"},"401":{"description":"Missing or invalid credential. Without a credential the body is an AEP problem and `WWW-Authenticate: AEP …` points to /.well-known/aep."},"403":{"description":"Instance not owned by this account"},"404":{"description":"Instance not found"}}}}}}