REST API

Search the catalog, post demand requests and manage your provider listings as JSON.

OpenAPI 3.1 document
Anonymous search
curl --fail-with-body 'https://opencoupler.com/api/v1/systems?q=medistar&pageSize=3'

Authentication

Create a key with the read scope in Settings. Send it in the Authorization header. The /me endpoint accepts a key with any scope. Anonymous traffic is limited to 30 requests per minute per IP. A key allows up to 120 requests per minute, shared across REST and MCP.

Check key identity
curl --fail-with-body -H "Authorization: Bearer $OPENCOUPLER_API_KEY" 'https://opencoupler.com/api/v1/me'

Write operations and private listing reads require a bearer key with the scope shown below. Send JSON bodies up to 64 KiB. Reuse an Idempotency-Key on retries of request, vote and note creation with the same input. A key used with different input returns HTTP 409.

Pagination and errors

Pass nextCursor back as cursor with the same filters and page size. A null cursor ends the list. Repeat the parameter for each filter value. Anonymous reads support If-None-Match.

Errors include error.code and error.message. Validation can also include error.issues with editor field paths. A limit response returns HTTP 429 with Retry-After.

Endpoints

GET /api/v1/systems

Find published systems by name or alias. Filter by industry, country, vendor, deployment, vendor API or availability. Use the returned slug to look up a system. With the default browse order or the demand and providers sorts, changing vote or waitlist counts can cause offset-based cursors to repeat or skip items.

cursor Optional
{"type":"string","maxLength":90,"pattern":"^[A-Za-z0-9_-]+$","description":"nextCursor from the previous response with the same filters"}
pageSize Optional
{"default":20,"type":"integer","minimum":1,"maximum":100}
q Optional
{"type":"string","maxLength":120}
industry Optional
{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}}
country Optional
{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":8}}
deployment Optional
{"maxItems":20,"type":"array","items":{"type":"string","enum":["on_premise","vendor_hosted","cloud","hybrid"]}}
vendorApi Optional
{"maxItems":20,"type":"array","items":{"type":"string","enum":["none","partner_only","paid","open","unknown"]}}
availability Optional
{"maxItems":20,"type":"array","items":{"type":"string","enum":["live","beta","directory","in_development","wanted"]}}
vendor Optional
{"type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$"}
sort Optional
{"type":"string","enum":["relevance","name","demand","providers","newest"]}
GET /api/v1/systems/{slug}

Get a published system and compare its public integrations by listing ID, capabilities, status and pricing.

slug Required
{"type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"System slug from search results"}
GET /api/v1/listings/{provider}/{listing}

Get the capabilities, access method, pricing and operating requirements of a published integration. Split its public ID into provider and listing.

provider Required
{"type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Provider slug"}
listing Required
{"type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Listing slug"}
GET /api/v1/providers

Browse active provider profiles with counts of their public integrations.

cursor Optional
{"type":"string","maxLength":90,"pattern":"^[A-Za-z0-9_-]+$","description":"nextCursor from the previous response with the same filters"}
pageSize Optional
{"default":20,"type":"integer","minimum":1,"maximum":100}
GET /api/v1/providers/{slug}

Get an active provider profile and its public integrations by provider slug.

slug Required
{"type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Provider slug"}
GET /api/v1/requests

Browse public requests for systems and capabilities, ordered by confirmed votes. Changing vote counts can cause offset-based cursors to repeat or skip items.

cursor Optional
{"type":"string","maxLength":90,"pattern":"^[A-Za-z0-9_-]+$","description":"nextCursor from the previous response with the same filters"}
pageSize Optional
{"default":20,"type":"integer","minimum":1,"maximum":100}
q Optional
{"type":"string","maxLength":120}
status Optional
{"type":"string","enum":["open","provider_interested","in_development","live","merged","closed"]}
POST /api/v1/requests

Post an integration request for a catalog system or propose a new system. Use the buyer's actual needs and use case. Returns the request ID and records the creator's first vote.

Requires write:requests.

JSON request body schema
{
  "type": "object",
  "properties": {
    "systemId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "proposedSystem": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 120
        },
        "vendor": {
          "type": "string",
          "maxLength": 120
        },
        "country": {
          "type": "string",
          "maxLength": 8
        },
        "website": {
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "name"
      ]
    },
    "title": {
      "type": "string",
      "minLength": 5,
      "maxLength": 140
    },
    "needs": {
      "default": [],
      "maxItems": 30,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "area": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "level": {
            "type": "string",
            "enum": [
              "read",
              "read_write"
            ]
          }
        },
        "required": [
          "area",
          "level"
        ]
      }
    },
    "useCase": {
      "default": "",
      "type": "string",
      "maxLength": 2000
    },
    "interfacesWanted": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 20
      }
    },
    "constraints": {
      "type": "string",
      "maxLength": 500
    },
    "timeline": {
      "type": "string",
      "enum": [
        "now",
        "within_3_months",
        "within_12_months",
        "exploring"
      ]
    },
    "requesterRole": {
      "type": "string",
      "enum": [
        "software_company",
        "it_service_provider",
        "end_customer",
        "agency",
        "individual_developer"
      ]
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "tender": {
      "type": "object",
      "properties": {
        "budgetMinMinor": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "budgetMaxMinor": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "currency": {
          "default": "EUR",
          "type": "string",
          "minLength": 3,
          "maxLength": 3
        },
        "deadline": {
          "anyOf": [
            {
              "type": "string",
              "format": "date",
              "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])))$"
            },
            {
              "type": "null"
            }
          ]
        },
        "visibility": {
          "default": "has_budget_only",
          "type": "string",
          "enum": [
            "public_amount",
            "has_budget_only"
          ]
        }
      }
    }
  },
  "oneOf": [
    {
      "required": [
        "systemId"
      ]
    },
    {
      "required": [
        "proposedSystem"
      ]
    }
  ]
}
Idempotency-Key Optional
{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","description":"A unique retry token for this mutation. Reuse it with the same arguments within 24 hours after a connection failure."}
GET /api/v1/requests/{id}

Get the needs, status and confirmed vote count of a public request by ID.

id Required
{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Public request ID"}
POST /api/v1/requests/{id}/votes

Vote for a public request as the key owner. One vote per account. Optionally include the data areas needed and a public use case.

Requires write:requests.

JSON request body schema
{
  "type": "object",
  "properties": {
    "needs": {
      "maxItems": 30,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "area": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "level": {
            "type": "string",
            "enum": [
              "read",
              "read_write"
            ]
          }
        },
        "required": [
          "area",
          "level"
        ]
      }
    },
    "useCase": {
      "type": "string",
      "maxLength": 2000
    },
    "role": {
      "type": "string",
      "enum": [
        "software_company",
        "it_service_provider",
        "end_customer",
        "agency",
        "individual_developer"
      ]
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    }
  }
}
id Required
{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Request ID from create_request or list_requests"}
Idempotency-Key Optional
{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","description":"A unique retry token for this mutation. Reuse it with the same arguments within 24 hours after a connection failure."}
DELETE /api/v1/requests/{id}/votes

Remove the key owner's vote from a request.

Requires write:requests.

id Required
{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Request ID from create_request or list_requests"}
POST /api/v1/requests/{id}/notes

Attach a public use-case note to a request. Describe the workflow and omit personal information. The author's account name is not displayed.

Requires write:requests.

JSON request body schema
{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "minLength": 10,
      "maxLength": 2000
    },
    "role": {
      "type": "string",
      "enum": [
        "software_company",
        "it_service_provider",
        "end_customer",
        "agency",
        "individual_developer"
      ]
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    }
  },
  "required": [
    "body"
  ]
}
id Required
{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"Request ID from create_request or list_requests"}
Idempotency-Key Optional
{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","description":"A unique retry token for this mutation. Reuse it with the same arguments within 24 hours after a connection failure."}
GET /api/v1/me/listings

List your organisations' listings, including drafts, review status and reviewer feedback. Use the provider and listing slugs in publicId for subsequent edits.

Requires write:listings.

provider Optional
{"description":"Your provider slug. Select one when you belong to multiple organisations.","type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$"}
PUT /api/v1/me/listings/{slug}

Save a full working copy for your provider's listing. Use get_system for systemId and the data-area keys. Fill in documented facts from your provider's website, using none for unsupported capabilities. The working copy stays private until you submit it and a human reviews it.

Requires write:listings.

JSON request body schema
{
  "type": "object",
  "properties": {
    "systemId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "Published system ID from get_system"
    },
    "title": {
      "type": "string",
      "maxLength": 240
    },
    "summary": {
      "type": "string",
      "maxLength": 640
    },
    "body": {
      "type": "string",
      "maxLength": 20000
    },
    "status": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "live",
            "beta",
            "in_development"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "expectedAt": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 10
        },
        {
          "type": "null"
        }
      ]
    },
    "capabilities": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 64
      },
      "additionalProperties": {
        "type": "string",
        "enum": [
          "none",
          "read",
          "read_write"
        ]
      }
    },
    "writeSafeguards": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "none",
            "user_confirmation",
            "approval_workflow"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "accessMethod": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "vendor_api_official",
            "vendor_api_partner",
            "local_database_readonly",
            "file_export",
            "ui_automation",
            "other"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "onSite": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "required": {
              "type": "boolean"
            },
            "os": {
              "default": [],
              "maxItems": 10,
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 40
              }
            },
            "note": {
              "type": "string",
              "maxLength": 500
            }
          },
          "required": [
            "required"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "interfaces": {
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "rest",
              "mcp",
              "cli",
              "webhooks",
              "sdk"
            ]
          },
          "docsUrl": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "authMethods": {
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "api_key",
          "oauth",
          "mtls",
          "other"
        ]
      }
    },
    "hosting": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "mode": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "provider_cloud",
                    "customer_on_prem",
                    "both"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "regions": {
              "default": [],
              "maxItems": 20,
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 8
              }
            },
            "note": {
              "type": "string",
              "maxLength": 500
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "dataHandling": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "mode": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "pass_through",
                    "cached",
                    "stored"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "retentionDays": {
              "anyOf": [
                {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "not": {}
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "subprocessors": {
              "type": "string",
              "maxLength": 1000
            },
            "note": {
              "type": "string",
              "maxLength": 1000
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "compliance": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "maxLength": 80
          },
          "scope": {
            "type": "string",
            "maxLength": 600
          },
          "validUntil": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 10
              },
              {
                "type": "null"
              }
            ]
          },
          "evidenceUrl": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "type",
          "scope"
        ]
      }
    },
    "pricing": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "model": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "per_system_month",
                    "per_site_month",
                    "per_user_month",
                    "usage",
                    "one_time",
                    "free",
                    "on_request"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "amountMinor": {
              "anyOf": [
                {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "not": {}
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "currency": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "EUR",
                    "USD",
                    "CHF",
                    "GBP"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "billingPeriod": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "month",
                    "year"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "usageUnit": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "1k_calls",
                    "gb"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "setupFeeMinor": {
              "anyOf": [
                {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "not": {}
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "minimumTermMonths": {
              "anyOf": [
                {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "not": {}
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "trialDays": {
              "anyOf": [
                {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "not": {}
                    }
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "freeTier": {
              "type": "string",
              "maxLength": 200
            },
            "pricesExcludeVat": {
              "type": "boolean"
            },
            "note": {
              "type": "string",
              "maxLength": 1000
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "onboarding": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "goLive": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "same_day",
                    "days_1_5",
                    "weeks_1_4",
                    "longer"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "steps": {
              "default": [],
              "maxItems": 10,
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 400
              }
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "support": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "languages": {
              "default": [],
              "maxItems": 10,
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 8
              }
            },
            "hours": {
              "type": "string",
              "maxLength": 400
            },
            "sla": {
              "type": "string",
              "maxLength": 400
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "countries": {
      "maxItems": 40,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 8
      }
    }
  },
  "required": [
    "systemId"
  ]
}
slug Required
{"type":"string","minLength":1,"maxLength":81,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Stable listing slug in your organisation, e.g. the system slug"}
provider Optional
{"description":"Your provider slug. Select one when you belong to multiple organisations.","type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$"}
POST /api/v1/me/listings/{slug}/submit

Submit the saved working copy after confirming its accuracy and accepting the terms. A human reviewer must approve it before the listing or revision goes public. Use list_my_listings to check the review state.

Requires write:listings.

JSON request body schema
{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "boolean",
      "description": "Set to true after confirming the listing's statements are accurate and accepting the marketplace terms."
    }
  },
  "required": [
    "confirm"
  ]
}
slug Required
{"type":"string","minLength":1,"maxLength":81,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Stable listing slug in your organisation, e.g. the system slug"}
provider Optional
{"description":"Your provider slug. Select one when you belong to multiple organisations.","type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$"}
POST /api/v1/me/listings/{slug}/unlist

Take your published listing off the public catalog and retain its working copy.

Requires write:listings.

slug Required
{"type":"string","minLength":1,"maxLength":81,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Stable listing slug in your organisation, e.g. the system slug"}
provider Optional
{"description":"Your provider slug. Select one when you belong to multiple organisations.","type":"string","minLength":1,"maxLength":160,"pattern":"^[a-z0-9][a-z0-9-]*$"}
GET /api/v1/me

Identify the API key owner and its scopes.