> ## Documentation Index
> Fetch the complete documentation index at: https://syteca.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Bridge for Ticketing Systems

> Integrate Syteca with any ticketing system — Jira, Freshservice, in-house, anything — via a self-hosted REST adapter. Build once, no Syteca product update required.

## Connect Syteca to any ticketing system — not just the supported few

Syteca integrates directly with **SysAid** and **ServiceNow**. But every organization has its own ticketing reality — Jira Service Management, Freshservice, BMC Remedy, Cherwell, a homegrown system built ten years ago that nobody wants to replace. Waiting for a vendor to add support for your specific system isn't an option when audit deadlines are real.

The **API Bridge** removes that dependency. It's a small REST service that **you** run, implementing a fixed three-endpoint interface Syteca calls. Build the adapter once in any language — Python, Go, .NET, Node, your existing internal stack — and Syteca can validate tickets against any platform you choose. New version of your ticketing system tomorrow? You update the Bridge, not Syteca.

<Info>
  **Use the API Bridge when you need to:**

  * Integrate Syteca with a ticketing system that isn't natively supported (Jira, Freshservice, custom, in-house).
  * Maintain ticketing integration independently of Syteca release cycles.
  * Build a thin adapter once and have it work for every privileged session going forward.
</Info>

This page explains why the API Bridge exists, the REST interface it must implement, and how to run the sample service to test the integration.

## What is the API Bridge?

Syteca's [ticketing system integration](/docs/administration/integrations/ticketing-system) can require users to enter a ticket number before they log in to a Client computer. Supporting many ticketing systems directly inside the product is difficult: each system has a different API, each new system needs a new adapter, and any change to a system's interface can require shipping a new version of Syteca.

The API Bridge solves this by inverting the relationship. Instead of Syteca implementing each ticketing system's API, Syteca defines one interface it expects, and you implement a service that satisfies that interface and talks to your ticketing system. The benefits:

* Add support for any ticketing system — including custom ones — without a Syteca update.
* Build the service in any language; only the interface matters.
* Update your Bridge whenever your ticketing system changes, independently of Syteca.

The API Bridge is a third-party [REST service](https://en.wikipedia.org/wiki/Representational_state_transfer) that you run. It must implement the specific REST interface described below.

<Frame caption="The API Bridge sits between Syteca and your ticketing system, implementing a single fixed interface.">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/syteca/images/api/integrations/api-bridge-architecture.png" alt="Diagram showing the API Bridge between Syteca and multiple ticketing systems" />
</Frame>

## The REST interface

Your API Bridge must implement the three endpoints below. Each one expands to show its parameters, request body, response schema, and example request and response in several languages.

<Info>
  These endpoints document the interface **your** Bridge implements — there is no Syteca-hosted server to call, so they are shown for reference only and have no live request panel. Your Bridge runs at your own address and port.
</Info>

<Card title="POST /connect — Request a session ID" icon="plug-zap" href="/docs/api/integrations/connect" horizontal>
  Establish a session with the ticketing system and receive a session ID for subsequent calls.
</Card>

<Card title="GET /ticket-status — Get the ticket status" icon="circle-check" href="/docs/api/integrations/ticket-status" horizontal>
  Validate that a ticket exists and is not closed. Returns status 0 (not found), 1 (active), or 2 (closed).
</Card>

<Card title="POST /add-ticket-comment — Add a comment to a ticket" icon="message-square-plus" href="/docs/api/integrations/add-ticket-comment" horizontal>
  Add a comment to the ticket, typically a link to the session in the monitoring results.
</Card>

### How to read the interface

Each path is an endpoint your service must expose. For example, `/connect` means that if your service runs at `http://127.0.0.1:8080/`, it must accept POST requests at `http://127.0.0.1:8080/connect`. Within `/connect`, the request body is optional.

The full machine-readable specification is available below for developers who want to generate a client or server stub.

<Accordion title="View the full OpenAPI specification" icon="file-code">
  ```yaml api-bridge-openapi.yaml theme={"system"}
  openapi: 3.0.0
  info:
    version: "1.0"
    title: "Syteca Ticketing System Integration API Bridge"
  tags:
    - name: bridge
  paths:
    /connect:
      post:
        summary: Request a session ID
        operationId: connect
        tags: [bridge]
        requestBody:
          required: false
          content:
            application/json:
              schema:
                type: object
                properties:
                  connectionString:
                    type: string
        responses:
          '200':
            description: A JSON object including the session ID.
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    sessionId:
                      type: string
          '422':
            description: Unprocessable Entity (wrong connection string).
          default:
            description: Unexpected error.
    /ticket-status:
      get:
        summary: Get the ticket status
        operationId: ticketStatus
        description: Used to validate that ticket exists and not closed.
        tags: [bridge]
        parameters:
          - name: sessionId
            in: query
            required: true
            schema:
              type: string
          - name: ticketId
            in: query
            required: true
            schema:
              type: string
        responses:
          '200':
            description: A JSON object including the ticket ID and status.
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    ticketId:
                      type: string
                    status:
                      type: number
          '401':
            description: Unauthorized (Invalid session).
          '404':
            description: A ticket with the specified ID was not found.
          default:
            description: Unexpected error.
    /add-ticket-comment:
      post:
        summary: Add a comment to a ticket
        operationId: addTicketComment
        description: Used to add a comment with a link to the monitoring results.
        tags: [bridge]
        requestBody:
          required: true
          content:
            application/json:
              schema:
                type: object
                required: [sessionId, ticketId, ticketComment]
                properties:
                  sessionId:
                    type: string
                  ticketId:
                    type: string
                  ticketComment:
                    type: string
        responses:
          '201':
            description: Ok.
          '401':
            description: Unauthorized (Invalid session).
          '404':
            description: A ticket with the specified ID was not found.
          default:
            description: Unexpected error.
  ```
</Accordion>

<Frame caption="The communication flow between the API Bridge and the Syteca Application Server service.">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/syteca/images/api/integrations/api-bridge-flow.png" alt="Sequence diagram of communication between the API Bridge and the Syteca server service" />
</Frame>

<Note>
  The source diagrams reference the legacy `EkranServer` service name. Confirm the current service name during review and update the diagram accordingly.
</Note>

## How to use the API Bridge

You can implement the service yourself in any language that suits your infrastructure. Two shortcuts are available:

* **Generate a stub from the OpenAPI spec.** A free tool such as [Swagger](https://swagger.io/) can generate a basic service from the specification above, in the language of your choice.
* **Start from the sample service.** Syteca provides an example service written in ASP.NET Core. You can compile it from source or run the prebuilt executable.

<Warning>
  The sample service is **not** a production-ready solution. It is for testing only, and is meant as a starting skeleton to help you implement your own ticketing system integration.
</Warning>

### Run the sample service

The sample includes a JSON file with a basic set of ticket numbers so you can quickly test the Bridge. The JSON file is included in the archive alongside the sample code.

<Steps>
  <Step title="Unpack the package">
    Unpack the `APIBridgePackage` archive.
  </Step>

  <Step title="Move the JSON file into place">
    Move the JSON file into the `wwwroot` folder.
  </Step>

  <Step title="Edit the JSON file">
    Open the JSON file in any text editor and define:

    * In the **Sessions** section: the user credentials of your ticketing system.
    * In the **Tickets** section: the name of the ticket the user must enter when logging in to the Client computer.

    <Note>
      By default there are three ticket statuses: `0` — ticket not found; `1` — ticket active; `2` — ticket closed.
    </Note>
  </Step>

  <Step title="Run the executable">
    In the `APIBridgeSampleBinaries` folder, run `IO.Swagger`.
  </Step>

  <Step title="Specify the port">
    In the console window, enter the port to use for the connection between Syteca and the ticketing system, then press **Enter**.

    <Note>
      This is the same port you enter in the Management Tool when configuring the ticketing system integration.
    </Note>
  </Step>

  <Step title="Note the URL">
    The ticketing system URL is shown in the console window. You'll use this when configuring the integration.
  </Step>
</Steps>

<Note>
  The screenshots and sample binaries referenced here date from an earlier release. Confirm the archive name, folder names (`wwwroot`, `APIBridgeSampleBinaries`), and the `IO.Swagger` executable name still match the current sample package during review.
</Note>

## Set up the Bridge in the Management Tool

Once your Bridge service is running, configure Syteca to use it. In the Management Tool, set the **Ticketing System** to **API Bridge** and enter the URL, port, login, and password. For the full steps, see [Ticketing System Integration](/docs/administration/integrations/ticketing-system).

## Related

<CardGroup cols={2}>
  <Card title="Ticketing system integration" icon="ticket" href="/docs/administration/integrations/ticketing-system">
    Enable and configure ticketing integration in the Management Tool.
  </Card>

  <Card title="SDK overview" icon="plug" href="/docs/api/overview">
    Other developer integration options for Syteca.
  </Card>
</CardGroup>