diff --git a/api/README.md b/api/README.md
new file mode 100644
index 0000000..02f9125
--- /dev/null
+++ b/api/README.md
@@ -0,0 +1,65 @@
+This directory contains protobuf files for the BBSim control API.
+
+# Examples
+
+```
+# start BBSim 
+
+    ./bbsim -i 8 -n 16 -ia false
+
+# get OLT status
+
+    curl -X GET http://127.0.0.1:50062/v1/olt | jq
+
+# get status of the OLT's PON ports
+
+    curl -X GET http://127.0.0.1:50062/v1/olt/ports/pon | jq
+
+# get status of all active ONUs
+
+    curl -X GET http://127.0.0.1:50062/v1/olt/onus | jq
+
+# get the status of the ONU with ONU-ID 2 (on PON port 1)
+
+    curl -X GET "http://127.0.0.1:50062/v1/olt/onus?onu_id=2&pon_port_id=1" | jq
+
+# activate single ONU with a given serial number:
+
+    curl -X POST http://127.0.0.1:50062/v1/olt/ports/1/onus/BBSM00000201 | jq
+
+# get the status of an ONU using its serial number:
+
+    curl -X GET http://127.0.0.1:50062/v1/olt/onus/BBSM00000201 | jq
+
+# deactivate ONU using its serial number:
+
+    curl -X DELETE  http://127.0.0.1:50062/v1/olt/onus/BBSM00000201 | jq
+
+# or 
+
+    curl -X DELETE  http://127.0.0.1:50062/v1/olt/onus?onu_serial=BBSM00000201 | jq
+```
+
+
+# Activate multiple ONUs
+```
+cat <<EOF > onus_request.json
+{
+  "onus": [
+    {
+      "pon_port_id": 1,
+      "onu_serial": "BBSIMONU0001"
+    },
+    {
+      "pon_port_id": 2,
+      "onu_serial": "BBSIMONU0002"
+    }
+  ]
+}
+EOF
+
+
+    curl -H  "Content-Type: application/json" -X POST "http://127.0.0.1:50062/v1/olt/onus" -d @onus_request.json
+
+
+```
diff --git a/api/bbsim.proto b/api/bbsim.proto
new file mode 100644
index 0000000..494f947
--- /dev/null
+++ b/api/bbsim.proto
@@ -0,0 +1,196 @@
+// Copyright (c) 2018 Open Networking Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at:
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+package bbsim.api.v1;
+
+import "google/api/annotations.proto";
+import "protoc-gen-swagger/options/annotations.proto";
+
+option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
+    info: {
+	title: "BBSim API";
+	version: "1.0";
+    };
+    schemes: HTTP;
+    consumes: "application/json";
+    produces: "application/json";
+    responses: {
+	key: "404";
+	value: {
+	    description: "Returned when the resource does not exist.";
+	    schema: {
+		    json_schema: {
+		      type: STRING;
+		}
+	    }
+	}
+    }
+};
+
+// OLT information
+message OLTInfo {
+    int64   olt_id = 1;
+    string  olt_serial = 2;
+    string  olt_ip = 3;
+    string  olt_state = 4;
+    string  olt_vendor = 5;
+}
+
+// ONU information
+message ONUInfo {
+    uint32 onu_id = 1;
+    uint32 pon_port_id = 2;
+    // ONU serial number
+    string onu_serial = 3;
+    // ONU oper state
+    string oper_state = 4;
+    // ONU internal state
+    string onu_state = 5;
+}
+
+// Bulk ONU operations
+message ONUs {
+    repeated ONUInfo onus = 1;
+}
+
+message ONURequest {
+    ONUInfo onu = 1;
+    ONUs onus_batch = 2;
+}
+
+// Port information
+message PortInfo {
+    string port_type = 1;
+    uint32 port_id = 2;
+    int32  pon_port_max_onus = 3;
+    uint32 pon_port_active_onus = 4;
+    string port_state = 5;
+    string alarm_state = 6;
+}
+
+// Bulk port information
+message Ports {
+    repeated PortInfo ports = 1;
+}
+
+// BBSim status
+message OLTStatusResponse {
+    OLTInfo olt = 1;
+    repeated PortInfo ports = 2;
+}
+
+// BBSim response message
+message BBSimResponse {
+    string status_msg = 1;
+}
+
+// ONU alarm request
+message ONUAlarmRequest {
+    // ONU serial number
+    string onu_serial = 1; 
+    // Alarm types are:
+    //   "signaldegrade"
+    //   "lossofomcichannel"
+    //   "lossofploam"
+    string alarm_type = 2;
+    // "on"/"off" indicates raised or cleared alarm 
+    string status = 3;                 }
+
+// OLT alarm request
+message OLTAlarmRequest {
+    uint32 port_id = 1;
+    string port_type = 2;
+    string status = 3;
+}
+
+// Device action
+message DeviceAction {
+    string device_type = 1;             // ONU or OLT
+    string device_serial_number = 2;    // Device serial number
+    string device_action = 3;           // soft or hard reboot
+}
+
+message Empty {}
+
+service BBSimService {
+
+    // Get current status of OLT
+    rpc OLTStatus(Empty) returns (OLTStatusResponse) {
+        option (google.api.http) = {
+            get : "/v1/olt"
+            additional_bindings {get : "/v1/olt/status"}
+        };
+    }
+
+    // Get status of a PON/NNI port
+    rpc PortStatus(PortInfo) returns (Ports) {
+        option (google.api.http) = {
+            get : "/v1/olt/ports/{port_type}"
+        };
+    }
+
+    // Get status of all or specific ONUs
+    rpc ONUStatus(ONURequest) returns (ONUs) {
+        option (google.api.http) = {
+            get : "/v1/olt/onus"
+            additional_bindings { get : "/v1/olt/ports/{onu.pon_port_id}/onus" }
+            additional_bindings { get : "/v1/olt/onus/{onu.onu_serial}" }
+        };
+    }
+
+    // Single/bulk activate ONU(s) for specific PON port(s)
+    rpc ONUActivate(ONURequest) returns (BBSimResponse) {
+        option (google.api.http) = {
+            post : "/v1/olt/onus"
+            body: "onus_batch"
+            additional_bindings { post : "/v1/olt/ports/{onu.pon_port_id}/onus" }
+            additional_bindings { post : "/v1/olt/ports/{onu.pon_port_id}/onus/{onu.onu_serial}" }
+        };
+    }
+    
+    // Deactivate ONU(s) for specific PON port(s) specified by  
+    // a given onu_serial, onu_id, or pon_port_id
+    rpc ONUDeactivate(ONURequest) returns (BBSimResponse) {
+        option (google.api.http) = {
+            delete : "/v1/olt/onus"
+            body: "onus_batch"
+            additional_bindings { delete: "/v1/olt/onus/{onu.onu_serial}" }
+            additional_bindings { delete: "/v1/olt/ports/{onu.pon_port_id}/onus" }
+            additional_bindings { delete: "/v1/olt/ports/{onu.pon_port_id}/onus/{onu.onu_id}" }
+        };
+    }
+
+    // Generate ONU related alarms
+    rpc GenerateONUAlarm(ONUAlarmRequest) returns (BBSimResponse) {
+        option (google.api.http) = {
+            post : "/v1/olt/onus/{onu_serial}/alarms/{alarm_type}/{status}"
+        };
+    }
+
+    // Generate OLT related alarms
+    rpc GenerateOLTAlarm(OLTAlarmRequest) returns (BBSimResponse) {
+        option (google.api.http) = {
+            post : "/v1/olt/ports/{port_type}/{port_id}/alarms/los/{status}"
+        };
+    }
+
+    // Perform actions on OLT/ONU devices (e.g. reboot)
+    rpc PerformDeviceAction(DeviceAction) returns (BBSimResponse) {
+        option (google.api.http) = {
+            patch: "/v1/{device_type}/reboot"
+            additional_bindings { patch : "/v1/olt/{device_type}/{device_serial_number}/reboot/{device_action}"}
+        };
+    }
+}
diff --git a/api/swagger/.gitignore b/api/swagger/.gitignore
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/api/swagger/.gitignore